# Stagger list (goodtabs UI)

A list that enters in sequence with a step capped so the whole entrance stays under 300ms.

## Install

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

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

## Usage

```tsx
import { StaggerList } from "@/components/ui/stagger-list"

<StaggerList items={["One", "Two", "Three"]} />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| items | `string[]` |  | The labels to list. |
| replayKey | `number` | `0` | Change it to play the entrance again. |

## When to use

- A short list that appears once, such as search results or menu entries
- Explaining why a stagger step should shrink as the list grows

## When not to use

- Lists that update often: replaying the entrance each time is noise
- Exit animations, which should stagger by no more than 20ms

## Notes for agents

- Registry dependency button is only used by the demos, the component itself needs motion alone
- Under reduced motion the items render in place with no initial state, so nothing is hidden
- Only opacity and transform animate, 150ms each

## The maths

- Step = min(50ms, 300ms / n), so 4 items step 50ms and 12 items step 25ms.
- Item i starts at i × step, so the last starts at (n - 1) × step, under 300ms.

Docs: https://ui.goodtabs.co/components/stagger-list