Migrating from lightGallery

lightGallery 3 ships under GPL-3.0 or a commercial license you pay for, so a closed-source project has to buy one. This package is MIT: free for any project, commercial or not, and there is no license key to set.

The React APIs are close. Both have a controlled mode with slides, open, index, onIndexChange and onClose, so most of a migration is renaming. This guide maps @lightgallery/react 3.0. See the comparison for how the two differ overall.

What has no equivalentCopy Anchor Link

Check this list first. If your gallery depends on one of these, this package is not a drop-in replacement:

• Wistia videos.
• The comment, medium zoom, relative caption and Vimeo thumbnail plugins.
• Inline galleries rendered inside the page with container. Here container only picks where the portal mounts.
• Facebook, X and Pinterest share buttons. Sharing goes through the system share sheet, with a copy-link fallback.
• Transitions other than slide, fade and zoom.

Install and importsCopy Anchor Link

- npm install @lightgallery/react lightgallery
+ npm install @esdrassantos06/gallery

- import { LightGallery } from "@lightgallery/react";
- import Thumbnail from "@lightgallery/react/plugins/thumbnail";
- import Zoom from "@lightgallery/react/plugins/zoom";
- import "lightgallery/css/lightgallery.css";
- import "lightgallery/css/lg-thumbnail.css";
- import "lightgallery/css/lg-zoom.css";
+ import { Lightbox } from "@esdrassantos06/gallery";
+ import "@esdrassantos06/gallery/styles.css";

There are no plugins to import and one stylesheet. Thumbnails, zoom and fullscreen are on by default. Video, YouTube and Vimeo work without setup.

Controlled galleriesCopy Anchor Link

- const [open, setOpen] = useState(false);
- const [index, setIndex] = useState(0);
+ const [index, setIndex] = useState(-1);

- <LightGallery
-   plugins={[Thumbnail, Zoom]}
-   slides={items}
-   open={open}
-   onClose={() => setOpen(false)}
-   index={index}
-   onIndexChange={setIndex}
- />
+ <Lightbox
+   slides={slides}
+   open={index >= 0}
+   index={Math.max(index, 0)}
+   onIndexChange={setIndex}
+   onClose={() => setIndex(-1)}
+ />

One index of -1 for "closed" is the usual pattern here, but a separate open state works too. Keep Lightbox mounted so the close animation can play.

Thumbnail triggersCopy Anchor Link

There is no LightGalleryItem. Render your own buttons and pass getThumbnail, which lightGallery does through lgSize and zoomFromOrigin. It makes the image fly out of the clicked thumbnail, cropped the same way, and returns focus to it on close.

const thumbnails = useRef<(HTMLButtonElement | null)[]>([]);

{
  slides.map((slide, i) => (
    <button
      key={slide.src}
      ref={(el) => {
        thumbnails.current[i] = el;
      }}
      onClick={() => setIndex(i)}
      aria-label={`Open ${slide.alt}`}
    >
      <img src={slide.thumbnail} alt="" />
    </button>
  ));
}

<Lightbox
  // ...
  getThumbnail={(i) => thumbnails.current[i]}
/>;

Or use one of the grids, which do this for you.

Items to slidesCopy Anchor Link

A YouTube or Vimeo link in src becomes an embed, as it does with lightGallery's video plugin. Self-hosted video files are detected from the extension, or set type: "video", and take sources and tracks. See Slides.

SettingsCopy Anchor Link

PluginsCopy Anchor Link

Justified gridCopy Anchor Link

- <LightGallery plugins={[Thumbnail, Zoom]}>
-   <JustifiedGrid rowHeight={180} gap={8}>
-     {items.map((item) => (
-       <LightGalleryItem key={item.src} item={item} data-lg-size={item.lgSize}>
-         <img src={item.thumb} alt={item.alt} />
-       </LightGalleryItem>
-     ))}
-   </JustifiedGrid>
- </LightGallery>
+ <JustifiedGrid ref={grid} slides={slides} onOpen={setIndex} rowHeight={180} gap={8} />
+ <Lightbox
+   slides={slides}
+   open={index >= 0}
+   index={Math.max(index, 0)}
+   onIndexChange={setIndex}
+   onClose={() => setIndex(-1)}
+   getThumbnail={(i) => grid.current?.getThumbnail(i)}
+ />

The grid reads width and height from each slide, so there is no data-lg-size. grid is a useRef<GridHandle>(null).

StylingCopy Anchor Link

The lightgallery/css/* files are replaced by one stylesheet and --eg-* CSS variables. The common ones:

The full list is in Styling.