# Lightbox

> A photo grid and fullscreen viewer on Base UI's Dialog. Each photo grows out of its thumbnail and shrinks back into it, cropped as the grid shows it. Swipe or arrow between photos, drag down to dismiss, double-tap, pinch, ctrl-scroll or press + to zoom and drag to pan. A tap hides the controls, a filmstrip follows along, and Escape steps out of a zoom first.

- Slug: `lightbox`
- Category: [Media](https://www.assembli.design/category/media.md)
- Type: component
- Tags: lightbox, gallery, image-viewer, zoom, swipe, fullscreen, photos, pinch
- npm dependencies: @base-ui/react, lucide-react
- shadcn/ui dependencies: none
- Live preview: https://www.assembli.design/preview/lightbox
- Page: https://www.assembli.design/components/lightbox

![Lightbox preview](https://www.assembli.design/thumbnails/lightbox-light.png)

## Props

Other props pass through to the root element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `LightboxItem[]` |  |  |
| `open` (required) | `boolean` |  |  |
| `onOpenChange` (required) | `(open: boolean) => void` |  |  |
| `index` (required) | `number` |  |  |
| `onIndexChange` (required) | `(index: number) => void` |  |  |
| `originOf` | `(index: number) => HTMLElement \| null` |  | The thumbnail element for an item. The photo grows out of it on open and shrinks back into it on close. |
| `container` | `HTMLElement \| React.RefObject<HTMLElement \| null> \| null` |  | Mount inside this element instead of `<body>`. |
| `hideOriginal` | `boolean` |  | Hide the "Open original" button. |

## Install

One-time setup (needs a subscription):

1. Add the registry to the project's `components.json`: `{"@assembli":{"url":"https://www.assembli.design/r/{name}.json","headers":{"Authorization":"Bearer ${ASSEMBLI_API_KEY}"}}}` (merge into `"registries"`).
2. Put an API key from https://www.assembli.design/account in `.env.local` as `ASSEMBLI_API_KEY=asm_…`.

Then install with the shadcn CLI (writes `components/lightbox/lightbox.tsx` and installs dependencies):

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

Registry item JSON: https://www.assembli.design/r/lightbox.json (send `Authorization: Bearer <api key>`)

## Code

> Component source needs an Assembli subscription ($12/month or $96/year) and an API key sent as `Authorization: Bearer <key>`. To get one without copying anything, POST https://www.assembli.design/api/agent/login (or call the MCP tool connect_account), show the user the link it returns, and poll https://www.assembli.design/api/agent/token for the key. Or subscribe at https://www.assembli.design/pricing and create a key at https://www.assembli.design/account.