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";

Property	Type	Description
open	boolean	If `true`, the lightbox is open.
close	() => void	A callback to close the lightbox.
index	number	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
slides	Slide[]	Slides to display in the lightbox. See Slide for details.
render	Render	Custom render functions. See Render for details.
plugins	Plugin[]	Enabled plugins. Example: plugins={[Fullscreen, Video]}
labels	object	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.
className	string	CSS 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.

Property	Type	Description
type	"image" \| undefined	Image slide type
src	string	Image URL
alt	string	Image `alt` attribute
width	number	Image width in pixels
height	number	Image 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;
}

slide - render custom slide type, or override the default image slide
slideHeader, slideFooter, slideContainer - render custom decorations around each slide
iconPrev, iconNext, iconClose, iconLoading, iconError - render custom icons
buttonPrev, buttonNext, buttonClose - render custom buttons (or hide the buttons by returning null)