Lightbox React component
An image lightbox for any grid of photos: the thumbnail morphs into the full view, then arrows, keys and swipes step through, double-click zooms and pans, a swipe down closes, and a thumbnail strip tracks where you are.
About the Lightbox component
Lightbox shows a grid of image thumbnails that open into a full-screen viewer, with the clicked thumbnail growing smoothly into the large image. The viewer has a caption, a counter, previous and next buttons, a strip of thumbnails along the bottom and a 2x zoom, and it closes with a swipe down, Escape or the close button.
images takes objects with src, alt, an optional caption and an optional smaller thumb for the grid and the strip. columns sets the grid columns. showGrid={false} hides the grid so you can open the viewer from your own layout with index and onIndexChange (null means closed). showThumbnails toggles the strip, loop wraps from the last image to the first, and contained keeps the viewer inside a positioned parent instead of covering the page. It is a modal dialog that takes focus and gives it back when closed.
When to use it
Use Lightbox wherever people should look at photos properly without leaving the page: product images, portfolios, event albums, user uploads. The thumbnail grows into the full view, so it's always clear which picture opened.
Use showGrid={false} with index when the thumbnails are part of your own layout (a product gallery, a feed) and you only need the viewer.
Installation
Add the Lightbox component to your project with the shadcn CLI. It lands in components/lightbox.tsx as plain React + Tailwind CSS source you own and can edit.
npx shadcn@latest add @reactframe/lightboxOr copy the source by hand and install its dependencies:
npm install motion clsx tailwind-mergeProps
<Lightbox /> accepts 10 props, all optional.
| Prop | Type | Default |
|---|---|---|
| images | { src: string; alt: string; caption?: string; thumb?: string }[] | DEFAULT_IMAGES |
| showGrid Render the clickable thumbnail grid. Turn off to open it yourself with index / onIndexChange. | boolean | true |
| columns | number | 3 |
| index The open image (null = closed). Leave out to let the grid manage it. | number | null | — |
| onIndexChange | (index: number | null) => void | — |
| showThumbnails | boolean | true |
| contained Keep the viewer inside the nearest positioned ancestor instead of covering the page. | boolean | false |
| loop | boolean | true |
| theme | "dark" | "light" | "dark" |
| className | string | — |
- images{ src: string; alt: string; caption?: string; thumb?: string }[]Default: DEFAULT_IMAGES
- showGrid
Render the clickable thumbnail grid. Turn off to open it yourself with index / onIndexChange.
booleanDefault: true - columnsnumberDefault: 3
- index
The open image (null = closed). Leave out to let the grid manage it.
number | null - onIndexChange(index: number | null) => void
- showThumbnailsbooleanDefault: true
- contained
Keep the viewer inside the nearest positioned ancestor instead of covering the page.
booleanDefault: false - loopbooleanDefault: true
- theme"dark" | "light"Default: "dark"
- classNamestring
npm dependencies
Installed for you by the shadcn CLI.
Lightbox FAQ
- How do people move between images?
- Arrow buttons, the keyboard's left and right arrows, swiping sideways, or tapping a thumbnail in the strip. Swiping down or pressing Escape closes it.
- Can images be zoomed?
- Yes. Double-click, press Z or use the zoom button for 2x; while zoomed, drag to look around.
- Does it cover the whole page?
- By default it's portalled to the body and covers the viewport. Set contained to keep it inside the nearest positioned container, e.g. a card or a preview.
- Should I pass smaller images for the thumbnails?
- Yes, for large photos. Give each image a thumb URL; the grid and the strip load that file, and the full src is used only in the viewer.
