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";
Lightbox
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 | { | Toolbar settings.
Default value: { buttons: ["close"] } |
carousel | { | Carousel settings.
Default value: { finite: false, preload: 2, padding: "16px", spacing: "30%", imageFit: "contain" } |
animation | { | Animation settings.
Default value: { fade: 330, swipe: 500 } |
controller | { | Controller settings.
Default value: { focus: true, aria: false, touchAction: "none" } |
on | { | Lifecycle callbacks.
|
styles | { | Customization styles.
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 | { | 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 slideslideHeader
,slideFooter
,slideContainer
- render custom decorations around each slideiconPrev
,iconNext
,iconClose
,iconLoading
,iconError
- render custom iconsbuttonPrev
,buttonNext
,buttonClose
- render custom buttons (or hide the buttons by returningnull
)