Yet Another React Lightbox

Common errors

• ReferenceError: Lightbox is not defined

  cause The Lightbox component was not imported or was imported incorrectly.
  fix Ensure you have `import Lightbox from 'yet-another-react-lightbox';` at the top of your file.

• Lightbox opens but images are not centered, background is white, or navigation arrows are missing/unstyled.

  cause The required CSS stylesheet for the lightbox was not imported.
  fix Add `import 'yet-another-react-lightbox/styles.css';` to your application's entry point or the component file where the Lightbox is used.

• TypeError: Cannot read properties of undefined (reading 'useState') or similar errors related to Hooks.

  cause Your React project is using a version older than 16.8.0, which does not support React Hooks.
  fix Upgrade your `react` and `react-dom` packages to version `^16.8.0` or newer in your `package.json` and reinstall dependencies.

• Property 'Zoom' does not exist on type 'typeof import("yet-another-react-lightbox")'.

  cause Attempting to import a plugin (like Zoom) directly from the main `yet-another-react-lightbox` package.
  fix Plugins must be imported from their specific paths, e.g., `import Zoom from 'yet-another-react-lightbox/plugins/zoom';`.

Warnings

• gotcha The base styles for the lightbox are not automatically included. You must explicitly import `yet-another-react-lightbox/styles.css` for the component to render with its intended appearance.
  Fix: Add `import 'yet-another-react-lightbox/styles.css';` to your entry file or a component where the Lightbox is used.
• gotcha Advanced features like image zoom, video support, captions, and thumbnails are implemented as separate plugins. These are not included by default to keep the core library lean and must be imported and added to the `plugins` prop of the `Lightbox` component.
  Fix: Import desired plugins (e.g., `import Zoom from 'yet-another-react-lightbox/plugins/zoom';`) and include them in the `plugins={[Zoom]}` array prop of the Lightbox component. Remember to also import any associated plugin CSS (e.g., `import 'yet-another-react-lightbox/plugins/zoom.css';`).
• gotcha Yet Another React Lightbox is built on React Hooks and requires React version 16.8.0 or newer. Using it with older React versions will result in runtime errors related to missing hooks.
  Fix: Ensure your project's `react` and `react-dom` peer dependencies are updated to `^16.8.0` or newer.
• gotcha While the basic `slides` array with just `src` works, the library strongly recommends providing `srcset` and `sizes` attributes for responsive images. This ensures optimal performance and user experience by allowing the browser to choose the most appropriate image resolution.
  Fix: For each image slide, provide `width`, `height`, and an array of `srcSet` objects containing different resolutions: `slides={[{ src: '/image.jpg', width: 1200, height: 800, srcSet: [{ src: '/image_sm.jpg', width: 320 }] }]}`.
• breaking Version 3 introduced minor breaking changes. Key changes included `slides` and `index` props being updatable (previously might have required workarounds), and animation easing settings moved to `animation` prop. While migration is generally trivial, review the v3 release notes if upgrading from v2.
  Fix: Review the full v3 changelog on GitHub. Ensure `slides` and `index` are treated as stable array references (e.g., using `useState` or `useMemo`). Adjust animation settings if custom easing was previously applied.

Install

• npm install yet-another-react-lightbox npm
• yarn add yet-another-react-lightbox yarn
• pnpm add yet-another-react-lightbox pnpm

Imports

• Lightbox
  wrong:

  const Lightbox = require('yet-another-react-lightbox');

  correct:

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

  The library primarily uses ES Module syntax. Using `require()` for the default export can lead to issues or require `Lightbox.default`.
• Lightbox styles

  import 'yet-another-react-lightbox/styles.css';

  This import is essential for the lightbox's default styling. Without it, the component will render unstyled.
• Zoom plugin
  wrong:

  import { Zoom } from 'yet-another-react-lightbox';

  correct:

  import Zoom from 'yet-another-react-lightbox/plugins/zoom';
  import 'yet-another-react-lightbox/plugins/zoom.css';

  Plugins like Zoom are modular and need to be imported from their specific paths, often with their own CSS. They are then passed to the `plugins` prop of the `Lightbox` component. Importing from the main package root for plugins is incorrect.

Quickstart

This example demonstrates the minimal setup for Yet Another React Lightbox, showing how to open and close the lightbox and provide a basic array of image slides.

import * as React from 'react';
import Lightbox from 'yet-another-react-lightbox';
import 'yet-another-react-lightbox/styles.css';

export default function App() {
  const [open, setOpen] = React.useState(false);

  return (
    <>
      <button type="button" onClick={() => setOpen(true)}>
        Open Lightbox
      </button>

      <Lightbox
        open={open}
        close={() => setOpen(false)}
        slides={[
          { src: '/image1.jpg' },
          { src: '/image2.jpg' },
          { src: '/image3.jpg' },
        ]}
      />
    </>
  );
}