Yet Another React Lightbox Lite

Lightweight React lightbox component. This is a trimmed-down version of the yet-another-react-lightbox that provides essential lightbox features and slick UX with just 4.6KB bundle size.

Overview

• Built for React: works with React 18+
• UX: supports keyboard, mouse, touchpad and touchscreen navigation
• Zoom: zoom is supported out of the box
• Performance: preloads a fixed number of images without compromising performance or UX
• Responsive: responsive images with automatic resolution switching are supported out of the box
• Customization: customize any UI element or add your own custom slides
• No bloat: supports only essential lightbox features
• TypeScript: type definitions come built-in in the package

Documentation

https://github.com/igordanchenko/yet-another-react-lightbox-lite

Examples

• Live demo - https://stackblitz.com/edit/yet-another-react-lightbox-lite
• Examples - https://stackblitz.com/edit/yet-another-react-lightbox-lite-examples

Changelog

https://github.com/igordanchenko/yet-another-react-lightbox-lite/releases

Requirements

• React 18+
• Node 18+
• modern ESM-compatible bundler

Installation

1npm install yet-another-react-lightbox-lite

Minimal Setup Example

1import { useState } from "react";
2import Lightbox from "yet-another-react-lightbox-lite";
3import "yet-another-react-lightbox-lite/styles.css";
4
5export default function App() {
6  const [index, setIndex] = useState<number>();
7
8  return (
9    <>
10      <button type="button" onClick={() => setIndex(0)}>
11        Open Lightbox
12      </button>
13
14      <Lightbox
15        slides={[
16          { src: "/image1.jpg" },
17          { src: "/image2.jpg" },
18          { src: "/image3.jpg" },
19        ]}
20        index={index}
21        setIndex={setIndex}
22      />
23    </>
24  );
25}

Responsive Images

To utilize responsive images with automatic resolution switching, provide srcset images in the slide srcSet array.

1<Lightbox
2  slides={[
3    {
4      src: "/image1x3840.jpg",
5      srcSet: [
6        { src: "/image1x320.jpg", width: 320, height: 213 },
7        { src: "/image1x640.jpg", width: 640, height: 427 },
8        { src: "/image1x1200.jpg", width: 1200, height: 800 },
9        { src: "/image1x2048.jpg", width: 2048, height: 1365 },
10        { src: "/image1x3840.jpg", width: 3840, height: 2560 },
11      ],
12    },
13    // ...
14  ]}
15  // ...
16/>

Next.js Image

If your project is based on Next.js, you may want to take advantage of the next/image component. The next/image component provides a more efficient way to handle images in your Next.js project. You can replace the standard <img> element with next/image with the following render.slide render function.

1<Lightbox
2  render={{
3    slide: ({ slide, rect }) => {
4      const width =
5        slide.width && slide.height
6          ? Math.round(
7              Math.min(rect.width, (rect.height / slide.height) * slide.width),
8            )
9          : rect.width;
10
11      const height =
12        slide.width && slide.height
13          ? Math.round(
14              Math.min(rect.height, (rect.width / slide.width) * slide.height),
15            )
16          : rect.height;
17
18      return (
19        <Image
20          src={slide.src}
21          alt={slide.alt || ""}
22          width={width}
23          height={height}
24          loading="eager"
25          draggable={false}
26          blurDataURL={(slide as any).blurDataURL}
27          style={{
28            minWidth: 0,
29            minHeight: 0,
30            maxWidth: "100%",
31            maxHeight: "100%",
32            objectFit: "contain",
33          }}
34        />
35      );
36    },
37  }}
38  // ...
39/>

API

Yet Another React Lightbox Lite comes with CSS stylesheet that needs to be imported in your app.

1import "yet-another-react-lightbox-lite/styles.css";

The lightbox component accepts the following props.

slides

Type: Slide[]

An array of slides to display in the lightbox. This prop is required. By default, the lightbox supports only image slides. You can add support for custom slides through a custom render function (see example below).

Image slide props:

• src - image source (required)
• alt - image alt attribute

index

Type: number | undefined

Current slide index. This prop is required.

setIndex

Type: (index: number | undefined) => void

A callback to update current slide index state. This prop is required.

labels

Type: keyof Labels

Custom UI labels / translations.

1<Lightbox
2  labels={{
3    Previous: t("Previous"),
4    Next: t("Next"),
5    Close: t("Close"),
6  }}
7  // ...
8/>

toolbar

Type: object

Toolbar settings.

• buttons - custom toolbar buttons (type: ReactNode[])
• fixed - if true, the toolbar is positioned statically above the carousel

Usage example:

1<Lightbox
2  toolbar={{
3    fixed: true,
4    buttons: [
5      <button
6        type="button"
7        className="yarll__button"
8        onClick={() => {
9          // ...
10        }}
11      >
12        <ButtonIcon />
13      </button>,
14    ],
15  }}
16  // ...
17/>

carousel

Type: object

Carousel settings.

• preload - the lightbox preloads (2 * preload + 1) slides (default: 2)
• imageProps - custom image slide attributes

Usage example:

1<Lightbox
2  carousel={{
3    preload: 5,
4    imageProps: { crossOrigin: "anonymous" },
5  }}
6  // ...
7/>

controller

Type: object

Controller settings.

• closeOnPullUp - if true, close the lightbox on pull-up gesture (default: true)
• closeOnPullDown - if true, close the lightbox on pull-down gesture (default: true)
• closeOnBackdropClick - if true, close the lightbox when the backdrop is clicked (default: true)

Usage example:

1<Lightbox
2  controller={{
3    closeOnPullUp: false,
4    closeOnPullDown: false,
5    closeOnBackdropClick: false,
6  }}
7  // ...
8/>

render

Type: object

An object providing custom render functions.

1<Lightbox
2  render={{
3    slide: ({ slide, rect, zoom, current }) => (
4      <CustomSlide {...{ slide, rect, zoom, current }} />
5    ),
6    slideHeader: ({ slide, rect, zoom, current }) => (
7      <SlideHeader {...{ slide, rect, zoom, current }} />
8    ),
9    slideFooter: ({ slide, rect, zoom, current }) => (
10      <SlideFooter {...{ slide, rect, zoom, current }} />
11    ),
12    controls: () => <CustomControls />,
13    iconPrev: () => <IconPrev />,
14    iconNext: () => <IconNext />,
15    iconClose: () => <IconClose />,
16  }}
17  // ...
18/>

slide: ({ slide, rect, zoom, current }) => ReactNode

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

Parameters:

• slide - slide object (type: Slide)
• rect - slide rect size (type: Rect)
• zoom - current zoom level (type: number)
• current - if true, the slide is the current slide in the viewport (type: boolean)

slideHeader: ({ slide, rect, zoom, current }) => ReactNode

Render custom elements above each slide.

slideFooter: ({ slide, rect, zoom, current }) => ReactNode

Render custom elements below or over each slide. By default, the content is rendered right under the slide. Alternatively, you can use position: "absolute" to position the extra elements relative to the slide.

For example, you can use the slideFooter render function to add slides descriptions.

1<Lightbox
2  render={{
3    slideFooter: ({ slide }) => (
4      <div style={{ marginBlockStart: 16 }}>{slide.description}</div>
5    ),
6  }}
7  // ...
8/>

controls: () => ReactNode

Render custom controls or additional elements in the lightbox (use absolute positioning).

For example, you can use the render.controls render function to implement slides counter.

1<Lightbox
2  render={{
3    controls: () =>
4      index !== undefined && (
5        <div style={{ position: "absolute", top: 16, left: 16 }}>
6          {index + 1} of {slides.length}
7        </div>
8      ),
9  }}
10  // ...
11/>

iconPrev: () => ReactNode

Render custom Previous icon.

iconNext: () => ReactNode

Render custom Next icon.

iconClose: () => ReactNode

Render custom Close icon.

styles

Type: { [key in Slot]?: SlotCSSProperties }

Customization slots styles allow you to specify custom CSS styles or override --yarll__* CSS variables by passing your custom styles through to the corresponding lightbox elements.

Supported customization slots:

• portal - lightbox portal (root)
• carousel - lightbox carousel
• slide - lightbox slide
• image - lightbox slide image
• toolbar - lightbox toolbar
• button - lightbox button
• icon - lightbox icon

Usage example:

1<Lightbox
2  styles={{
3    portal: { "--yarll__backdrop_color": "rgba(0, 0, 0, 0.6)" },
4  }}
5  // ...
6/>

className

Type: string

CSS class of the lightbox root element. You can use this class name to provide module-scoped style overrides.

zoom

Type: object

Zoom settings.

• disabled - disable zoom on image slides
• supports - zoom-enabled custom slide types

Usage example:

1<Lightbox
2  zoom={{ supports: ["custom-slide-type"] }}
3  // ...
4/>

Custom Slide Attributes

You can add custom slide attributes with the following module augmentation.

1declare module "yet-another-react-lightbox-lite" {
2  interface GenericSlide {
3    description?: string;
4  }
5}

Custom Slides

You can add custom slide types through module augmentation and render them with the render.slide render function.

Here is an example demonstrating video slides implementation.

1declare module "yet-another-react-lightbox-lite" {
2  interface SlideVideo extends GenericSlide {
3    type: "video";
4    src: string;
5    poster: string;
6    width: number;
7    height: number;
8  }
9
10  interface SlideTypes {
11    video: SlideVideo;
12  }
13}
14
15// ...
16
17<Lightbox
18  slides={[
19    {
20      type: "video",
21      src: "/media/video.mp4",
22      poster: "/media/poster.jpg",
23      width: 1280,
24      height: 720,
25    },
26  ]}
27  render={{
28    slide: ({ slide }) =>
29      slide.type === "video" ? (
30        <video
31          controls
32          playsInline
33          poster={slide.poster}
34          width={slide.width}
35          height={slide.height}
36          style={{ maxWidth: "100%", maxHeight: "100%" }}
37        >
38          <source type="video/mp4" src={slide.src} />
39        </video>
40      ) : undefined,
41  }}
42  // ...
43/>;

Code Splitting (Suspense)

1// Lightbox.tsx
2import LightboxComponent, {
3  LightboxProps,
4} from "yet-another-react-lightbox-lite";
5import "yet-another-react-lightbox-lite/styles.css";
6
7export default function Lightbox(props: LightboxProps) {
8  return <LightboxComponent {...props} />;
9}

1// App.tsx
2import { lazy, Suspense, useState } from "react";
3import slides from "./slides";
4
5const Lightbox = lazy(() => import("./Lightbox"));
6
7export default function App() {
8  const [index, setIndex] = useState<number>();
9
10  return (
11    <>
12      <button type="button" onClick={() => setIndex(0)}>
13        Open Lightbox
14      </button>
15
16      {index !== undefined && (
17        <Suspense>
18          <Lightbox slides={slides} index={index} setIndex={setIndex} />
19        </Suspense>
20      )}
21    </>
22  );
23}

Body Scroll Lock

By default, the lightbox hides the browser window scrollbar and prevents document <body> from scrolling underneath the lightbox by assigning the height: 100%; overflow: hidden; styles to the document <body> element.

If this behavior causes undesired side effects in your case, and you prefer not to use this feature, you can turn it off by assigning the yarll__no_scroll_lock class to the lightbox.

1<Lightbox
2  className="yarll__no_scroll_lock"
3  // ...
4/>

However, if you keep the body scroll lock feature on, you may notice a visual layout shift of some fixed-positioned page elements when the lightbox opens. To address this, you can assign the yarll__fixed CSS class to your fixed-positioned elements to keep them in place. Please note that the fixed-positioned element container should not have its own border or padding styles. If that's the case, you can always add an extra wrapper that just defines the fixed position without visual styles.

Text Selection

The lightbox is rendered with the user-select: none CSS style. If you'd like to make some of your custom elements user-selectable, use the yarll__selectable CSS class. This class sets the user-select: text style and turns off click-and-drag slide navigation, likely interfering with text selection UX.

Hooks

The library exports the following hooks that you may find helpful in customizing lightbox functionality.

useZoom

You can use the useZoom hook to build your custom zoom controls.

1import { useZoom } from "yet-another-react-lightbox-lite";

The hook provides an object with the following props:

• rect - slide rect
• zoom - current zoom level (numeric value between 1 and 8)
• maxZoom - maximum zoom level (1 if zoom is not supported on the current slide)
• offsetX - horizontal slide position offset
• offsetY - vertical slide position offset
• changeZoom - change zoom level
• changeOffsets - change position offsets

License

MIT © 2024 Igor Danchenko