# Stepper (goodtabs UI)

Numbered steps with hairline connectors, one current, the rest done or upcoming.

## Install

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

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

## Usage

```tsx
import { Stepper } from "@/components/ui/stepper"

<Stepper
  current={1}
  steps={[{ label: "Account" }, { label: "Workspace" }, { label: "Done" }]}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| steps | `{ label: string; description?: string }[]` |  | The steps, in order. |
| current | `number` | `0` | Index of the current step. Everything before it is done. |
| orientation | `"horizontal" | "vertical"` | `"horizontal"` | A row with hairlines between, or a stack with a hairline down the left. |
| onStepClick | `(index: number) => void` |  | Makes done steps buttons and reports the clicked index. |

## When to use

- Multi-step forms, onboarding and checkout where people need to know where they are
- Vertical, with descriptions, as a setup checklist next to the form
- When steps happen in order and earlier ones can be revisited

## When not to use

- For switching between unordered views, use segmented tabs
- For a single loading or completion percentage, use a progress bar
- For more than six steps: group them first

## Notes for agents

- Server component by default; pass onStepClick from a client component and only done steps become buttons
- Horizontal labels hide under a 448px container (@md) so four circles always fit; descriptions show from 672px
- The li of the current step carries aria-current="step" and every step has a data-state of done, current or upcoming
- Keep labels short: they never wrap horizontally, so long labels push the connectors to their 16px minimum

Docs: https://ui.goodtabs.co/components/stepper