A grid of pictures that opens each one large, with arrows, swipes and captions.
$ pnpm dlx shadcn@latest add @dashral/lightboxInstallation
$ pnpm dlx shadcn@latest add @dashral/lightboxAdds the component, the components it builds on, its npm packages and the theme tokens it uses. Or by its full URL: https://dashral.com/r/lightbox.json
Usage
example.tsx
import { Lightbox } from "@/components/dashral/lightbox"
<Lightbox images={photos.map((photo) => ({ src: photo.url, alt: photo.alt, caption: photo.caption }))} columns={3} />Using the npm package? Import from @dashral/ui/components/lightbox instead, here and in the examples; the rest is the same.
Examples
API reference
Lightbox
| Prop | Type | Default |
|---|---|---|
images | { src, alt, thumbnail?, caption?, width?, height? }[]The pictures. Required. | — |
columns | 2 | 3 | 4 | 5The thumbnails' columns from the sm breakpoint (two on phones). | 3 |
ratio | numberThe thumbnails' shape. | 4 / 3 |
thumbnails | booleanfalse: no grid, open it yourself with open and index. | true |
open / onOpenChange | Control the viewer. | — |
index / onIndexChange | numberThe picture shown, from 0. | — |
imageAs | ElementTypeYour image component, e.g. Next.js Image. | "img" |
classNames | { grid, thumbnail, viewer, image, caption }Classes for each part. | — |
className | stringThe grid's classes. | — |
Keyboard
| Keys | Action |
|---|---|
| EnterorSpace | Open the picture (on a thumbnail) |
| ←or→ | The previous or next picture (in reading order: reversed in Arabic) |
| HomeorEnd | The first or last picture |
| Escape | Close, back to the thumbnail it came from |
Accessibility
- Each thumbnail is a button named "View" and its alt text. The viewer is a dialog named by the picture's alt; focus stays inside.
- The position ("2 of 6") is announced as it changes.
- Its words come from the kit's messages, so a LocaleProvider translates them.
Motion
- The viewer fades and grows in on the spring. Moving between pictures, the one on screen stays until the next has loaded, then the two cross: the old one fades out toward the side it's left on, the new one fades in from the side it comes from (reversed in Arabic). A sideways swipe moves between them on a touch screen.