React PhotoSwipe Gallery Component

Common errors

• TypeError: Cannot read properties of undefined (reading 'current') OR TypeError: ref is not a function

  cause Incorrectly assigning or failing to assign the `ref` object provided by the `Item` component's render prop to the actual DOM element, especially after the v3.0.0 `ref` handling changes.
  fix Ensure the `ref` prop passed down from the `Item` component's render function is correctly assigned to your `<img>` or `<a>` element, like `ref={ref as React.MutableRefObject<HTMLImageElement>}` (for TypeScript) or `ref={(el) => { if (ref) ref.current = el; }}` for a callback pattern.

• Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: undefined. You likely forgot to export your component from the file it's defined in, or you might have mixed up default and named imports.

  cause Attempting to render `Item` outside of `Gallery` or using an incorrect import statement (e.g., a default import instead of a named import for `Item`).
  fix Verify that `Item` components are always direct children of a `Gallery` component. Ensure `Item` is imported as a named export: `import { Item } from 'react-photoswipe-gallery'`.

• PhotoSwipe: Core has not been initialized. OR PhotoSwipe is not defined.

  cause Missing the required PhotoSwipe CSS import, or `photoswipe` itself is not correctly installed or compatible with the `react-photoswipe-gallery` version.
  fix First, install `photoswipe` (`npm install photoswipe`) and ensure its version is compatible. Then, add `import 'photoswipe/dist/photoswipe.css';` to your application's entry point or relevant component file to include the necessary styles.

Warnings

• breaking As of v4.0.0, the `caption` prop for the `Item` component no longer supports raw HTML content. This change was implemented to mitigate potential Cross-Site Scripting (XSS) vulnerabilities.
  Fix: Refactor captions to use plain text only. If rich text is essential, consider rendering it externally or sanitizing any HTML content rigorously before passing it, although direct HTML is no longer officially supported for security reasons.
• breaking Version 3.0.0 introduced significant changes to how `ref` props are handled for `Item` components. The `ref` type transitioned from a ref object to a ref callback, and passing `ref` to the underlying DOM node became mandatory even for single items. Manual casting of `ref` is also no longer required.
  Fix: Update `Item` components to use the ref callback pattern correctly. Ensure the `ref` provided by the render prop is always assigned to the target HTML element, e.g., `ref={ref as React.MutableRefObject<HTMLElement>}` in TypeScript, and remove any explicit `ref` casting if previously used.
• gotcha This library has a strict peer dependency on `photoswipe`. Incompatible versions between `react-photoswipe-gallery` and `photoswipe` can lead to runtime errors, unexpected behavior, or a completely non-functional gallery. Consult `react-photoswipe-gallery`'s `package.json` for the exact compatible `photoswipe` version range.
  Fix: Ensure that your installed `photoswipe` package version adheres to the peer dependency requirements specified by `react-photoswipe-gallery`. Upgrade or downgrade `photoswipe` as necessary to match the expected range.
• gotcha Prior to v4.0.0, the `caption` prop in the `Item` component was vulnerable to Cross-Site Scripting (XSS) attacks if unsanitized user-generated HTML was passed directly. This was addressed by removing HTML support in v4.0.0.
  Fix: It is strongly recommended to upgrade to `react-photoswipe-gallery` v4.0.0 or later to benefit from the built-in XSS protection. If upgrading is not immediately possible, meticulously sanitize all content provided to the `caption` prop to prevent arbitrary script execution.

Install

• npm install react-photoswipe-gallery npm
• yarn add react-photoswipe-gallery yarn
• pnpm add react-photoswipe-gallery pnpm

Imports

• Gallery
  wrong:

  const { Gallery } = require('react-photoswipe-gallery')

  correct:

  import { Gallery } from 'react-photoswipe-gallery'

  This library primarily uses ES Module imports. CommonJS `require` syntax may not work as expected or is not recommended.
• Item
  wrong:

  import Item from 'react-photoswipe-gallery'

  correct:

  import { Item } from 'react-photoswipe-gallery'

  `Item` is a named export and must be destructured from the package. It represents an individual image within the gallery.
• useGallery
  wrong:

  import { UseGallery } from 'react-photoswipe-gallery'

  correct:

  import { useGallery } from 'react-photoswipe-gallery'

  A React Hook for programmatic control over the gallery, such as opening/closing. It's a named export, ensure correct camelCase spelling.

Quickstart

This example demonstrates how to set up a basic image gallery using the `Gallery` and `Item` components. It includes the necessary PhotoSwipe CSS, custom options for the gallery, and correctly handles image references and click events to open the lightbox, showcasing two sample images.

import React, { useRef } from 'react';
import { Gallery, Item } from 'react-photoswipe-gallery';
import 'photoswipe/dist/photoswipe.css'; // Essential PhotoSwipe base styles

const MyPhotoGallery: React.FC = () => {
  return (
    <Gallery
      options={{
        bgOpacity: 0.8,
        zoomAnimationDuration: 300
      }}
    >
      <Item
        original="https://picsum.photos/id/1018/1000/600/"
        thumbnail="https://picsum.photos/id/1018/100/60/"
        width="1000"
        height="600"
        caption="A serene landscape from Unsplash"
        cropped
      >
        {({ ref, open }) => (
          <img
            ref={ref as React.MutableRefObject<HTMLImageElement>}
            onClick={open}
            src="https://picsum.photos/id/1018/100/60/"
            alt="Landscape thumbnail"
            style={{ cursor: 'pointer', margin: '5px', borderRadius: '4px' }}
          />
        )}
      </Item>
      <Item
        original="https://picsum.photos/id/1015/1000/600/"
        thumbnail="https://picsum.photos/id/1015/100/60/"
        width="1000"
        height="600"
        caption="Abstract patterns and colors"
        cropped
      >
        {({ ref, open }) => (
          <img
            ref={ref as React.MutableRefObject<HTMLImageElement>}
            onClick={open}
            src="https://picsum.photos/id/1015/100/60/"
            alt="Abstract thumbnail"
            style={{ cursor: 'pointer', margin: '5px', borderRadius: '4px' }}
          />
        )}
      </Item>
    </Gallery>
  );
};

export default MyPhotoGallery;