Yet Another React Lightbox

https://yet-another-react-lightbox.com/documentation
Admin
Yet Another React Lightbox is a React component library that enables developers to add interactive...
Tokens:3,492
Snippets:31
Trust Score:7.4
Update:6 months ago
Show doc for...
Tokens:
Raw
### Control Lightbox Externally with Controller Ref

Source: https://yet-another-react-lightbox.com/documentation

Use React.useRef to get a ref to the Lightbox component for external control. Access methods like close() via ref.current.

```javascript
const ref = React.useRef(null);

// ...

return (
  <Lightbox
    controller={{ ref }}
    on={{ click: () => ref.current?.close() }}
    // ...
  />
);
```

--------------------------------

### Define Responsive Image Slides

Source: https://yet-another-react-lightbox.com/documentation

Recommended configuration providing multiple resolutions via srcSet for optimized loading.

```javascript
const slides = [
  {
    src: "/image1x3840.jpg",
    alt: "image 1",
    width: 3840,
    height: 2560,
    srcSet: [
      { src: "/image1x320.jpg", width: 320, height: 213 },
      { src: "/image1x640.jpg", width: 640, height: 427 },
      { src: "/image1x1200.jpg", width: 1200, height: 800 },
      { src: "/image1x2048.jpg", width: 2048, height: 1365 },
      { src: "/image1x3840.jpg", width: 3840, height: 2560 },
    ],
  },
  // ...
];
```

--------------------------------

### RTL Configuration

Source: https://yet-another-react-lightbox.com/documentation

Configuring the lightbox reading direction for RTL languages.

```APIDOC
## RTL Configuration

### Description
The lightbox detects direction from the root element or can be configured per-instance.

### Configuration
- **Portal-based**: Use `portal={{ container: { dir: "rtl" } }}`
- **Inline/Carousel**: Use `inline={{ dir: "rtl" }}`
```

--------------------------------

### Customization Styles

Source: https://yet-another-react-lightbox.com/documentation

Allows for custom styling of various lightbox components.

```APIDOC
## Customization Styles

### Description

Provides slots for applying custom CSS properties to different parts of the lightbox.

### Properties

- **root** (CSSProperties) - Optional - Customizes the lightbox root element.
- **container** (CSSProperties) - Optional - Customizes the lightbox container.
- **slide** (CSSProperties) - Optional - Customizes the lightbox slide.
- **button** (CSSProperties) - Optional - Customizes the lightbox buttons.
- **icon** (CSSProperties) - Optional - Customizes the lightbox icons.

*Note: Some plugins may extend this list with additional customization slots.*

```

--------------------------------

### Import Lightbox Styles

Source: https://yet-another-react-lightbox.com/documentation

Import the CSS stylesheet for Yet Another React Lightbox. This should be done once in your project. You can omit this if styles are already included.

```javascript
import "yet-another-react-lightbox/styles.css";
```

--------------------------------

### Set RTL Direction Per-Instance (Portal)

Source: https://yet-another-react-lightbox.com/documentation

For the default portal-based lightbox, set the RTL direction for a specific instance using the portal.container prop.

```javascript
<Lightbox portal={{ container: { dir: "rtl" } }} />
```

--------------------------------

### Define Basic Image Slides

Source: https://yet-another-react-lightbox.com/documentation

Minimal configuration for image slides requiring only the src attribute.

```javascript
const slides = [
  { src: "/image1.jpg" },
  { src: "/image2.jpg" },
  { src: "/image3.jpg" },
  // ...
];
```

--------------------------------

### Tracking Slide Index

Source: https://yet-another-react-lightbox.com/documentation

How to synchronize the internal lightbox slide index with a local state variable.

```APIDOC
## Tracking Slide Index

### Description
Use the 'index' prop and 'view' event handler to keep track of the current slide index in local state.

### Request Example
const [index, setIndex] = React.useState(0);
<Lightbox index={index} on={{ view: ({ index: currentIndex }) => setIndex(currentIndex) }} />
```

--------------------------------

### Lifecycle Callbacks

Source: https://yet-another-react-lightbox.com/documentation

Callbacks that are triggered at various stages of the lightbox's lifecycle.

```APIDOC
## Lifecycle Callbacks

### Description

These callbacks allow you to hook into different events during the lightbox's lifecycle.

### Properties

- **view** (function) - Optional - Called when a slide becomes active. Receives `{ index: number }`.
- **click** (function) - Optional - Called when a slide is clicked. Receives `{ index: number }`.
- **entering** (function) - Optional - Called when the portal starts opening.
- **entered** (function) - Optional - Called when the portal opens.
- **exiting** (function) - Optional - Called when the portal starts closing.
- **exited** (function) - Optional - Called when the portal closes.

```

--------------------------------

### Image Slide Configuration

Source: https://yet-another-react-lightbox.com/documentation

Defines the structure and properties for image slides within the lightbox.

```APIDOC
## Slide - Image

### Description

Image slides are supported by default. You can also add custom slide types via plugins or a custom render function.

### Properties

- **type** ("image") - Required - Specifies the slide type as an image.
- **src** (string) - Required - The URL of the image.
- **alt** (string) - Optional - The `alt` attribute for the image.
- **width** (number) - Optional - The width of the image in pixels. Required if `srcSet` is provided.
- **height** (number) - Optional - The height of the image in pixels. Required if `srcSet` is provided.
- **imageFit** ("contain" | "cover") - Optional - Sets the `object-fit` CSS property for the image.
- **srcSet** (array) - Optional - An array of image sources with different resolutions for `srcset` attribute.
  - Each item in `srcSet` should have:
    - **src** (string) - Image URL.
    - **width** (number) - Image width in pixels.
    - **height** (number) - Image height in pixels.

### Minimum Configuration

At a minimum, the `src` attribute must be provided for each image slide.

```javascript
const slides = [
  { src: "/image1.jpg" },
  { src: "/image2.jpg" },
  { src: "/image3.jpg" },
  // ...
];
```

### Recommended Configuration with `srcSet`

For optimal performance and responsiveness, provide multiple image resolutions. The lightbox will automatically populate `srcset` and `sizes` attributes.

```javascript
const slides = [
  {
    src: "/image1x3840.jpg",
    alt: "image 1",
    width: 3840,
    height: 2560,
    srcSet: [
      { src: "/image1x320.jpg", width: 320, height: 213 },
      { src: "/image1x640.jpg", width: 640, height: 427 },
      { src: "/image1x1200.jpg", width: 1200, height: 800 },
      { src: "/image1x2048.jpg", width: 2048, height: 1365 },
      { src: "/image1x3840.jpg", width: 3840, height: 2560 },
    ],
  },
  // ...
];
```

*Note: Providing a large number of slides has no performance penalty due to optimized preloading.*
```

--------------------------------

### Controller Ref API

Source: https://yet-another-react-lightbox.com/documentation

The Controller ref provides an interface to programmatically control the lightbox instance from outside the component.

```APIDOC
## Controller Ref API

### Description
Provides external control methods for the lightbox instance via a React ref.

### Methods
- **prev** ({ count }: { count: number }) => void - Navigate to the previous slide.
- **next** ({ count }: { count: number }) => void - Navigate to the next slide.
- **close** () => void - Close the lightbox.
- **focus** () => void - Transfer focus to the lightbox controller.
- **getLightboxProps** () => ComponentProps - Get current lightbox props.
- **getLightboxState** () => LightboxState - Get current lightbox state.

### Request Example
const ref = React.useRef(null);
<Lightbox controller={{ ref }} on={{ click: () => ref.current?.close() }} />
```

--------------------------------

### Custom Render Functions

Source: https://yet-another-react-lightbox.com/documentation

Defines how to use custom render functions to override default rendering of lightbox components.

```APIDOC
## Render

### Description

Custom render functions can be passed via the `render` prop to customize the appearance and behavior of various lightbox elements.

### Usage Example

```javascript
<Lightbox
  render={{
    slide: ({ slide, offset, rect }) => {
      // Custom slide rendering logic
    },
  }}
  // ... other props
/>
```

### Render Props

- **slide** (function) - Optional - Renders a custom slide type or overrides the default image slide. Receives `{ slide: Slide; offset: number; rect: ContainerRect }`.
- **slideHeader** (function) - Optional - Renders custom elements into the DOM right before the slide. Use absolute or fixed positioning. Receives `{ slide: Slide }`.
- **slideFooter** (function) - Optional - Renders custom elements into the DOM right after the slide. Use absolute or fixed positioning. Receives `{ slide: Slide }`.
- **slideContainer** (function) - Optional - Renders a custom slide container. Receives `{ slide: Slide; children: React.ReactNode }`.
- **controls** (function) - Optional - Renders custom controls or additional elements in the lightbox. Use absolute or fixed positioning. Receives no arguments.
- **iconPrev** (function) - Optional - Renders a custom Prev icon. Receives no arguments.
- **iconNext** (function) - Optional - Renders a custom Next icon. Receives no arguments.
- **iconClose** (function) - Optional - Renders a custom Close icon. Receives no arguments.
- **iconLoading** (function) - Optional - Renders a custom Loading icon. Receives no arguments.
- **iconError** (function) - Optional - Renders a custom Error icon. Receives no arguments.
- **buttonPrev** (function) - Optional - Renders a custom Prev button. Return `null` to hide the button. Receives no arguments.
- **buttonNext** (function) - Optional - Renders a custom Next button. Return `null` to hide the button. Receives no arguments.
- **buttonClose** (function) - Optional - Renders a custom Close button. Receives no arguments.

```

--------------------------------

### Lightbox Component Properties

Source: https://yet-another-react-lightbox.com/documentation

Configuration properties for the Lightbox component to control state, content, and behavior.

```APIDOC
## Lightbox Component Properties

### Description
Configuration properties for the Lightbox component to control state, content, and behavior.

### Parameters
- **open** (boolean) - Required - If true, the lightbox is open.
- **close** (() => void) - Required - A callback to close the lightbox.
- **index** (number) - Optional - Slide index. Default: 0.
- **slides** (Slide[]) - Optional - Slides to display in the lightbox. Default: [].
- **render** (Render) - Optional - Custom render functions.
- **plugins** (Plugin[]) - Optional - Enabled plugins.
- **labels** (object) - Optional - Custom UI labels / translations.
- **toolbar** (object) - Optional - Toolbar settings (buttons: (React.ReactNode | "close")[])
- **carousel** (object) - Optional - Carousel settings (finite, preload, padding, spacing, imageFit, imageProps)
- **animation** (object) - Optional - Animation settings (fade, swipe, navigation, easing)
- **controller** (object) - Optional - Controller settings (ref, focus, aria, touchAction, closeOnPullUp, closeOnPullDown, closeOnBackdropClick, disableSwipeNavigation)
- **portal** (object) - Optional - Portal settings (root, container)
- **noScroll** (object) - Optional - NoScroll module settings (disabled)
```

--------------------------------

### Lightbox Root ClassName

Source: https://yet-another-react-lightbox.com/documentation

Specifies a CSS class for the root element of the lightbox.

```APIDOC
## ClassName

### Description

Applies a custom CSS class to the root element of the lightbox for further styling.

### Properties

- **className** (string) - Optional - CSS class for the lightbox root element.

```

--------------------------------

### Set RTL Direction Per-Instance (Inline Plugin)

Source: https://yet-another-react-lightbox.com/documentation

When using the Inline plugin in carousel mode, pass the 'dir' prop via the inline prop to set the RTL direction.

```javascript
<Lightbox plugins={[Inline]} inline={{ dir: "rtl" }} />
```

--------------------------------

### NoScroll Module Configuration

Source: https://yet-another-react-lightbox.com/documentation

Configuration options for the NoScroll module, which manages scroll behavior and padding for fixed-position elements.

```APIDOC
## NoScroll Module

### Description

The NoScroll module manages scroll behavior and adds padding to fixed-position elements to prevent layout shifts. It can be disabled globally or for specific elements.

### Properties

- **disabled** (boolean) - Optional - If `true`, the NoScroll module functionality is disabled.

### CSS Class for Disabling Padding

To deactivate the padding behavior for specific elements, mark them with the `yarl__no_scroll_padding` CSS class.

```

--------------------------------

### Implement Custom Render Functions

Source: https://yet-another-react-lightbox.com/documentation

Usage of the render prop to override default slide rendering or add custom elements.

```jsx
// render function usage example

<Lightbox
  render={{
    slide: ({ slide, offset, rect }) => {
      // ...
    },
  }}
  // ...
/>
```

--------------------------------

### Track Slide Index with Local State

Source: https://yet-another-react-lightbox.com/documentation

Synchronize the lightbox's slide index with your component's local state. Update your state when the lightbox view changes using the 'view' event.

```javascript
const [index, setIndex] = React.useState(0);

// ...

return (
  <Lightbox
    index={index}
    on={{ view: ({ index: currentIndex }) => setIndex(currentIndex) }}
    // ...
  />
);
```

--------------------------------

### Set RTL Direction via HTML Attribute

Source: https://yet-another-react-lightbox.com/documentation

The lightbox automatically detects RTL direction from the 'dir' attribute on an ancestor element, such as the html tag.

```html
<html lang="fa" dir="rtl">
  <!-- ... -->
</html>
```
Tokens:
Raw