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. The below documentation covers Yet Another React Lightbox API.

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

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 only when it opens. Changing this property while the lightbox is already open has no effect.

Default value: 0

slidesSlide[]
Slides to display in the lightbox. See Slide for details.
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?: string | 0;
  spacing?: string | 0;
  imageFit?: "contain" | "cover"
}

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

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

animation

{
  fade?: number;
  swipe?: number;
}

Animation settings.

  • fade - fade-in / fade-out animation duration
  • swipe - swipe animation

Default value: { fade: 330, swipe: 500 }

controller

{
  focus?: boolean;
  aria?: boolean;
  touchAction?: "none" | "pan-y";
  closeOnBackdropClick?: boolean;
}

Controller settings.

  • 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
  • closeOnBackdropClick - if true, close the lightbox when the backdrop is clicked

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

on

{
  view?: (index: number) => void;
  click?: (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.

PropertyTypeDescription
type"image" | undefinedImage 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, which accepts an object of the following shape.

interface Render {
    slide?: (slide: Slide, offset: number, rect: ContainerRect) => React.ReactNode;
    slideHeader?: (slide: Slide) => React.ReactNode;
    slideFooter?: (slide: Slide) => React.ReactNode;
    slideContainer?: (slide: Slide, children: React.ReactNode) => React.ReactNode;
    iconPrev?: () => React.ReactNode;
    iconNext?: () => React.ReactNode;
    iconClose?: () => React.ReactNode;
    iconLoading?: () => React.ReactNode;
    iconError?: () => React.ReactNode;
    buttonPrev?: () => React.ReactNode;
    buttonNext?: () => React.ReactNode;
    buttonClose?: () => React.ReactNode;
}