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.

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:

PropertyTypeDescription
contains(target: string) => boolean
Test if the target module is present.
addParent(target: string, module: Module) => void
Add module as a parent of the target module.
addChild(target: string, module: Module, precede?: boolean) => void

Add module as a child of the target module.

  • precede - if true, prepend to the list of the existing children, or append otherwise
addSibling(target: string, module: Module, precede?: boolean) => void

Add module as a sibling of the target module.

  • precede - if true, insert right before the target module, or right after otherwise
addModule(module: Module) => void
Append module to the Controller module.
replace(target: string, module: Module) => void
Replace the target module.
append(target: string, module: Module) => void
Add module as a child of the target module and inherit its existing children.
remove(target: string) => void
Remove the target module.
augment(augmentation: Augmentation) => voidAugment the lightbox 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.)

PropertyTypeDescription
slidesSlide[]Lightbox slides.
currentIndexnumberCurrent slide index.
globalIndexnumberCurrent slide index in the (-∞, +∞) range.
currentSlideSlide | undefinedCurrent slide.
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.

PropertyTypeDescription
prev({ count }: { count: number }) => void | () => voidNavigate to the previous slide.
next({ count }: { count: number }) => void | () => voidNavigate to the next slide.
close() => voidClose the lightbox.
focus() => voidTransfer focus to the lightbox controller.
slideRect{ width: number; height: number }Container dimensions excluding slide padding.
containerRect{ width: number; height: number }Container dimensions.
containerRefReact.RefObject​<HTMLDivElement>
Container <div/> ref.
subscribeSensorsSubscribeSensorsSubscribe to pointer / keyboard / wheel events.
toolbarWidthnumber | undefinedCurrent toolbar width.

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

declare module "yet-another-react-lightbox" {
  interface Labels {
    "My button"?: string;
  }
}

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

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

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

// ...

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" }}
  // ...
/>