# Lightbox

> Thumbnail grid that opens a full-screen viewer with swipe, arrows and captions.

Component · Pro · https://lodeui.com/components/lightbox

## When to use

- Galleries, portfolios, product photos and attachments.

## When not to use

- One image: link to it or use the image lens.

## Installation

```bash
npx shadcn@latest add @lode/lightbox
```

Pro: needs a Lode API key and the `@lode` registry in components.json. See https://lodeui.com/docs/cli.

npm dependencies: motion, lucide-react

## Usage

```tsx title="example.tsx"
import { Lightbox } from "@/components/ui/lightbox";

<Lightbox images={photos.map((p) => ({ id: p.id, src: p.url, alt: p.alt, caption: p.caption }))} />
```

## API reference

### Lightbox

A thumbnail grid that opens a full-screen modal viewer.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| images | `{ id; src?; render?; alt; caption? }[]` | – | URLs, or render for custom content. |
| columns | `2 \| 3 \| 4` | `3` | Grid columns (2 on phones). |

## Keyboard interactions

| Keys | Action |
| --- | --- |
| Enter | Open a thumbnail |
| ← / → | Previous or next |
| Esc | Close and return to the thumbnail |

## Accessibility

- A modal dialog labelled with the image and its position; the caption is announced.
- Focus returns to the thumbnail you opened.

## Motion

- The thumbnail grows into the viewer; paging slides; swipe on touch.

## Responsive behavior

- Arrows hide on phones in favor of swiping.

## Performance

- Only the current image is mounted in the viewer.

## Notes for AI

- Give every image a meaningful alt.

## Related

- [Image lens](https://lodeui.com/components/image-lens) — A magnifying glass that follows the pointer (or arrow keys) over an image.
- [Carousel](https://lodeui.com/components/carousel) — Swipeable slides with arrows, animated dots, keys and pausable autoplay.
- [Morphing dialog](https://lodeui.com/components/morphing-dialog) — A card that morphs into a dialog: cover, title and frame fly to their new places.