Advanced API

Learn how to customize the lightbox with your own plugins using the lightbox core API.

Modules

The lightbox uses modular design, allowing you to modify the configuration of the existing modules or add your own modules via plugins. Each module is a named React component receiving pre-processed lightbox props and its children. By default, the modules are arranged in the following React components tree.

• Portal - lightbox portal module

  • NoScroll - removes scrollbars and prevents <body/> from scrolling

    • Controller - handles events from input devices and lightbox animation

      • Carousel - slides carousel
      • Toolbar - toolbar module
      • Navigation - navigation buttons

To create your own module, use the createModule function.

import { createModule } from "yet-another-react-lightbox";

// ...

function MyComponent({ children, ...props }) {
  // ...
  return <>{children}</>;
}

const myModule = createModule("MyModule", MyComponent);

Plugins

Each plugin is a function that receives a single parameter with the following named props:

For example, you can add your module to the lightbox with the following plugin:

import Lightbox from "yet-another-react-lightbox";

// ...

function MyPlugin({ addModule }) {
  addModule(MyModule);
}

// ...

return (
  <Lightbox
    plugins={[MyPlugin]}
    // ...
  />
);

Augmentation

Lightbox props can be modified with plugin's augment method. All plugins' augmentations are applied before the lightbox starts rendering.

For example, you can add a toolbar button using the following augmentation:

import { addToolbarButton } from "yet-another-react-lightbox";

// ...

function MyPlugin({ augment }) {
  augment(({ toolbar, ...restProps }) => ({
    toolbar: addToolbarButton(toolbar, "my-button", <MyButton />),
    ...restProps,
  }));
}

Another common use case for props augmentation is to provide the default values for props that are added with your plugin.

const myPropDefaults = {
  // ...
};

function MyPlugin({ augment }) {
  augment(({ myProp, ...restProps }) => ({
    myProp: { ...myPropDefaults, ...myProp },
    ...restProps,
  }));
}

Hooks

You can use the following hooks to access various lightbox features. All lightbox hooks can be used only in a component rendered inside the lightbox (i.e., a component rendered through a custom render function, or a component added to the lightbox with a plugin).

useLightboxState

The useLightboxState hook returns the current state of the lightbox (current slide, current index, etc.)

import { useLightboxState } from "yet-another-react-lightbox";

// ...

const { slides, currentSlide, currentIndex } = useLightboxState();

useLightboxProps

The useLightboxProps hook provides access to the lightbox props.

import { useLightboxProps } from "yet-another-react-lightbox";

// ...

const { carousel, render } = useLightboxProps();

useController

The useController hook provides access to the Controller module.

useContainerRect

The useContainerRect hook allows you to measure the available space of an HTML element excluding padding.

import { useContainerRect } from "yet-another-react-lightbox";

const { containerRect, setContainerRef } = useContainerRect();

// ...

<div ref={setContainerRef}>// ...</div>;

Toolbar Buttons

You can create custom toolbar buttons by using the IconButton component and the createIcon helper function.

import {
  Lightbox,
  IconButton,
  createIcon,
  useLightboxState,
} from "yet-another-react-lightbox";

const MyIcon = createIcon("MyIcon", <path d="..." />);

function MyButton() {
  const { currentSlide } = useLightboxState();

  return (
    <IconButton label="My button" icon={MyIcon} disabled={!currentSlide} />
  );
}

// ...

return (
  <Lightbox
    toolbar={{
      buttons: [<MyButton key="my-button" />, "close"],
    }}
    // ...
  />
);

Custom Slides

Register custom slide type in TypeScript:

// yet-another-react-lightbox.d.ts

import { GenericSlide } from "yet-another-react-lightbox";

declare module "yet-another-react-lightbox" {
  export interface CustomSlide extends GenericSlide {
    type: "custom-slide";
    // custom slide attributes
  }

  interface SlideTypes {
    "custom-slide": CustomSlide;
  }
}

// App.tsx

import { Lightbox, Slide, CustomSlide } from "yet-another-react-lightbox";

function isCustomSlide(slide: Slide): slide is CustomSlide {
  return slide.type === "custom-slide";
}

// ...

return (
  <Lightbox
    slides={[
      {
        type: "custom-slide",
        // custom slide attributes
      },
    ]}
    render={{
      slide: ({ slide }) =>
        isCustomSlide(slide) ? <MyCustomSlide slide={slide} /> : undefined,
    }}
    //...
  />
);

Custom Slide Props

You can use TypeScript module augmentation to add custom slide props.

declare module "yet-another-react-lightbox" {
  interface GenericSlide {
    customSlideProp?: string;
  }

  interface SlideImage {
    customImageSlideProp?: string;
  }
}

<Lightbox
  slides={[
    {
      src: "/image1.jpg",
      customSlideProp: "foo",
      customImageSlideProp: "bar",
    },
  ]}
  // ...
/>

Custom Lightbox Props

You can use TypeScript module augmentation to add custom lightbox props.

declare module "yet-another-react-lightbox" {
  interface LightboxProps {
    customLightboxProp?: {
      myProp?: string;
    };
  }
}

<Lightbox
  customLightboxProp={{ myProp: "baz" }}
  // ...
/>