Documentation

Yet Another React Lightbox allows you to add a lightbox component to your React project in minutes. To get started, follow the Installation and Minimal Setup Example guides, or feel free to explore the collection of CodeSandbox demos.

Yet Another React Lightbox provides all components and types as named exports. Lightbox is exported as both default and named export.

The below documentation covers Yet Another React Lightbox API. For advanced features, please see the Advanced API documentation.

Parameters marked with an asterisk () are required.

Styles

Yet Another React Lightbox comes with CSS stylesheet that needs to be imported once in your project. All examples across this site include CSS import, but you can omit the import statement if you already imported lightbox styles in your application.

import "yet-another-react-lightbox/styles.css";
PropertyTypeDescription
openboolean
If true, the lightbox is open.
close() => voidA callback to close the lightbox.
indexnumber

Starting slide index.

The lightbox reads this property when it opens and when either slides or index props change. In most cases, you do not need to update this property manually, as the lightbox maintains its state internally. You may need to update the index prop when you modify or completely replace the slides array. When the index property changes, the lightbox renders the specified slide without an animation effect. To navigate to a different slide with an animation effect, use the corresponding controller.ref method.

Default value: 0

slidesSlide[]

Slides to display in the lightbox. See Slide for details.

Please note that updating the slides array (or just changing the array reference) forces the lightbox to update its state based on the current slides and index values. You can safely use a non-stable array reference (i.e., slides={[...]} or slides={items.map((item) => ({...}))}) as long as the component holding the lightbox does not re-rerender while the lightbox is open. However, if your component may re-render, be sure to provide the slides prop as a stable array reference (i.e., const in static scope, or wrapped with React.useState or React.useMemo).

Default value: []

renderRender
Custom render functions. See Render for details.
pluginsPlugin[]

Enabled plugins.

Example: plugins={[Fullscreen, Video]}

labelsobject

Custom UI labels.

Example: labels={{ Next: "Next slide" }}

toolbar

{
  buttons: (React.ReactNode | "close")[];
}

Toolbar settings.

  • buttons - buttons to render in the toolbar

Default value: { buttons: ["close"] }

carousel

{
  finite?: boolean;
  preload?: number;
  padding?: `${number}px` | `${number}%` | number;
  spacing?: `${number}px` | `${number}%` | number;
  imageFit?: "contain" | "cover"
  imageProps?: React.ImgHTMLAttributes​<HTMLImageElement>
}

Carousel settings.

  • finite - if true, the lightbox carousel doesn't wrap around
  • preload - the lightbox preloads (2 * preload + 1) slides
  • padding - padding around each slide
  • spacing - spacing between slides
  • imageFit - object-fit setting for image slides
  • imageProps - custom image attributes

Default value: { finite: false, preload: 2, padding: "16px", spacing: "30%", imageFit: "contain" }

animation

{
  fade?: number;
  swipe?: number;
  navigation?: number;
  easing?: {
    fade?: string;
    swipe?: string;
    navigation?: string;
  }
}

Animation settings.

  • fade - fade-in / fade-out animation duration
  • swipe - swipe animation duration
  • navigation - override for swipe animation duration when using keyboard navigation or navigation buttons
  • easing - animation timing function settings
    • fade - fade-in / fade-out animation timing function
    • swipe - slide swipe animation timing function
    • navigation - slide navigation animation timing function (when using keyboard navigation or navigation buttons)

Default value: { fade: 250, swipe: 500, easing: { fade: "ease", swipe: "ease-out", navigation: "ease-in-out" } }

controller

{
  ref?: React.ForwardedRef​<ControllerRef>;
  focus?: boolean;
  aria?: boolean;
  touchAction?: "none" | "pan-y";
  closeOnPullDown?: boolean;
  closeOnBackdropClick?: boolean;
}

Controller settings.

  • ref - lightbox controller ref (see Controller Ref for details)
  • focus - if true, the lightbox captures focus when it opens
  • aria - if true, set ARIA attributes on the controller div
  • touchAction - controller touch-action setting
  • closeOnPullDown - if true, close the lightbox on pull-down gesture
  • closeOnBackdropClick - if true, close the lightbox when the backdrop is clicked

Default value: { ref: null, focus: true, aria: false, touchAction: "none" }

portal

{
  root?: DocumentFragment | Element | null;
}

Portal settings.

  • root - custom portal mount point. By default, the portal is mounted as a child of the document body.
on

{
  view?: ({ index }: { index: number }) => void;
  click?: ({ index }: { index: number }) => void;
  entering?: () => void;
  entered?: () => void;
  exiting?: () => void;
  exited?: () => void;
}

Lifecycle callbacks.

  • view - a callback called when a slide becomes active
  • click - a callback called when a slide is clicked
  • entering - a callback called when the portal starts opening
  • entered - a callback called when the portal opens
  • exiting - a callback called when the portal starts closing
  • exited - a callback called when the portal closes
styles

{
  root?: CSSProperties;
  container?: CSSProperties;
  button?: CSSProperties;
  icon?: CSSProperties;
}

Customization styles.

  • root - lightbox root customization slot
  • container - lightbox container customization slot
  • button - lightbox button customization slot
  • icon - lightbox icon customization slot

Note that some plugins extend this list with their own customization slots.

classNamestringCSS class of the lightbox root element

Slide

Image slides are supported by default. Additional slide types can be added via plugins or custom render function. Please see Custom Slides example for details.

PropertyTypeDescription
type"image"Image slide type
srcstringImage URL
altstring
Image alt attribute
widthnumberImage width in pixels
heightnumberImage height in pixels
imageFit"contain" | "cover"
Image object-fit setting
srcSet

{
  src: string;
  width: number;
  height: number;
}

Alternative images to be included in the srcset

As a bare minimum, you need to provide src attribute for each image slide.

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

However, the recommended configuration is to provide multiple files of different resolution for each slide. Yet Another React Lightbox uses all supplied images to populate srcset and sizes attributes on the fly.

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 },
    ]
  },
  // ...
];

Yet Another React Lightbox is optimized to preload and display only a limited number of slides at a time, so there are no performance penalties or UX impact in supplying a large number of slides.

Render

Custom render functions can be passed via render prop.

// render function usage example

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

({ slide, offset, rect }: { slide: Slide; offset: number; rect: ContainerRect }) => React.ReactNode

Render custom slide type, or override the default image slide.
slideHeader

({ slide }: { slide: Slide }) => React.ReactNode

Render custom slide elements into the DOM right before the slide. Use absolute or fixed positioning.
slideFooter

({ slide }: { slide: Slide }) => React.ReactNode

Render custom slide elements into the DOM right after the slide. Use absolute or fixed positioning.
slideContainer

({ slide, children }: { slide: Slide; children: React.ReactNode }) => React.ReactNode

Render custom slide container.
controls() => React.ReactNodeRender custom controls or additional elements in the lightbox. Use absolute or fixed positioning.
iconPrev() => React.ReactNodeRender custom Prev icon.
iconNext() => React.ReactNodeRender custom Next icon.
iconClose() => React.ReactNodeRender custom Close icon.
iconLoading() => React.ReactNodeRender custom Loading icon.
iconError() => React.ReactNodeRender custom Error icon.
buttonPrev() => React.ReactNode
Render custom Prev button. Return null if you want to hide the button.
buttonNext() => React.ReactNode
Render custom Prev button. Return null if you want to hide the button.
buttonClose() => React.ReactNodeRender custom Close button.

Controller Ref

Controller ref provides external controls for the lightbox.

// Controller ref usage example

const ref = React.useRef(null);

// ...

<Lightbox
  controller={{ ref }}
  on={{ click: () => ref.current?.close() }}
  // ...
/>
PropertyTypeDescription
prev({ count }: { count: number }) => void | () => voidNavigate to the previous slide.
next({ count }: { count: number }) => void | () => voidNavigate to the next slide.
close() => voidClose the lightbox.
focus() => voidTransfer focus to the lightbox controller.
getLightboxProps() => ComponentPropsGet lightbox props (see type definitions for more details).
getLightboxState() => LightboxStateGet lightbox state (see type definitions for more details).

Previous Versions

Are you looking for documentation for one of the previous versions?