# Expand gallery (goodtabs UI)

A thumbnail grid where each image grows into a full view inside a real dialog.

## Install

```bash
npx shadcn@latest add https://ui.goodtabs.co/r/expand-gallery.json
```

Or, with the @goodtabs namespace configured in components.json: `npx shadcn@latest add @goodtabs/expand-gallery`

## Usage

```tsx
import { ExpandGallery, ExpandGalleryItem } from "@/components/ui/expand-gallery"

<ExpandGallery aria-label="Studies">
  <ExpandGalleryItem src="/work/one.jpg" alt="The new dashboard" title="Dashboard" caption="1440 x 900" />
</ExpandGallery>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| ratio | `number` | `1.5` | On ExpandGallery. Width over height of the full view. Match your thumbnails. |
| src | `string` |  | On ExpandGalleryItem. The image, used for the thumbnail and the full view. |
| alt | `string` |  | On ExpandGalleryItem. Also names the button that opens it. |
| title | `ReactNode` |  | On ExpandGalleryItem. Shown under the full view, and names the dialog. |
| caption | `ReactNode` |  | On ExpandGalleryItem. One line of mono meta beside the title. |

## When to use

- A portfolio or case study where each image deserves a full look
- A short set of screenshots that lose their detail at thumbnail size
- When the way back to the grid should be obvious

## When not to use

- Long image feeds: every thumbnail loads the full image
- Images that must never crop, because the full view keeps one ratio
- Content that needs its own page or link

## Notes for agents

- GSAP installs from npm under GSAP's own licence. No GSAP code ships in this registry
- It uses the native dialog element with showModal, so focus, inert background and Escape come from the browser
- Thumbnails and the full view must share a ratio or the grow stretches. All images are cropped with object-cover
- Set the column span of an item with className. The default grid is two columns, then four from md up

## The maths

- The full view is min(100vw - 3rem, (100dvh - 10rem) × ratio) wide, so it fits either way with room for its caption.
- Flip.fit starts the view at thumbnail width over full width, 263 / 960 = 0.27 on a 1280 by 800 screen, and only transform moves.

Docs: https://ui.goodtabs.co/components/expand-gallery