# Stepper

Shows the steps of a flow in order and where the user is (checkout, onboarding, setup). Completed steps are buttons that go back to that step; upcoming steps cannot be reached from here. Use Tabs for switching views, not for a sequence.

## Usage

### When to use

- Show where someone is in an ordered flow such as checkout, onboarding or setup.
- Let someone return to a completed step without opening upcoming steps early.

### When not to use

- Switch between views of the same content. Use Tabs.
- Show how much work is complete without naming sequential steps. Use Progress.
- Navigate between pages or sections. Use Sidebar or BottomNav.

## Variants

### orientation

Row or column. In a column each label sits beside its indicator and the connector runs down to the next one. Use vertical below md when labels do not fit, or in a side column.

Values: `horizontal`, `vertical`. Default: `horizontal`.

### size

Indicator 24, 32 or 40px with 12, 16 or 20px icons; label font-size-sm, -md or -lg. sm for side columns and panels, lg for a roomy onboarding page. One size per region.

Values: `sm`, `md`, `lg`. Default: `md`.

## Examples

### Checkout

```tsx
<Stepper current={1} steps={checkoutSteps} onStepSelect={goToStep} />
```

### Vertical with descriptions

Each label sits on its indicator's center line, with the description under it.

```tsx
<Stepper orientation="vertical" current={1} steps={setupSteps} onStepSelect={goToStep} />
```

### With icons

A step's icon replaces its number until the step is complete.

```tsx
<Stepper current={2} steps={iconSteps} onStepSelect={goToStep} />
```

### Small, in a side column

```tsx
<Stepper orientation="vertical" size="sm" current={1} steps={setupSteps} onStepSelect={goToStep} />
```

## Do and don't

### Do

- Keep labels to one or two words.
- Use 3 to 7 steps; more needs grouping.
- Give every step an icon, or none.
- Show the step count in the page heading too (Step 2 of 4) when the Stepper is hidden on small screens.

### Don't

- Do not use Tabs for a sequence the user must follow in order.
- Do not use as navigation to steps the user has not reached.
- Do not mix two sizes of Stepper on one screen.

## Props

| Name | Type | Values | Default | Description |
| --- | --- | --- | --- | --- |
| `steps` (required) | `{ id: string; label: string; description?: string; status?: "error"; icon?: React.ReactNode }[]` |  |  | The steps in order. icon replaces the number on a current or upcoming step; the indicator sets its size and color, and completed and error steps keep their check and warning icons. status error overrides the computed visual state of that step. |
| `current` (required) | `number` |  |  | Zero-based index of the current step. Steps before it are complete. |
| `orientation` | `enum` | `horizontal`, `vertical` | `horizontal` | Row or column. In a column each label sits beside its indicator and the connector runs down to the next one. Use vertical below md when labels do not fit, or in a side column. |
| `size` | `enum` | `sm`, `md`, `lg` | `md` | Indicator 24, 32 or 40px with 12, 16 or 20px icons; label font-size-sm, -md or -lg. sm for side columns and panels, lg for a roomy onboarding page. One size per region. |
| `onStepSelect` | `(index: number) => void` |  |  | Called with the index when a completed step is activated, to go back to it. Required by the type when current is greater than zero, because an earlier step can be activated. |
| `statusLabels` | `{ completed?: string; current?: string; upcoming?: string; error?: string; goBack?: string }` |  |  | Words added to each step's accessible name, as {label}, {status}: { completed, current, upcoming, error }. Defaults: completed, current step, not reached, has an error. Vietnamese: đã xong, bước hiện tại, chưa đến, có lỗi. goBack names a completed step button: EN `{label}, completed, go back to this step`, VI `{label}, đã xong, quay lại bước này`. |

### Slots

| Name | Required | Description |
| --- | --- | --- |
| `stepIcon` | no | Optional icon per step, replacing the number on a current or upcoming step (never the check or warning icon). Any SVG node; the indicator sets its size and color. |

## Anatomy

| Part | Description |
| --- | --- |
| `root` | The ol that lays out the steps in a row or a column. |
| `step` | One li: its content (a button on a completed step) and its connectors. In a row, the indicator sits above the label; in a column, beside it, with space below for the connector. |
| `indicator` | The filled circle, with no outline: the step number or the step's icon, a check when complete, a warning icon on error. 24, 32 or 40px by size. |
| `stepIndicator` | The indicator inside a completed step's button. Hover and press darken the circle only, not a box around the label. |
| `icon` | Any icon in the indicator (the step's own, the check, the warning): 12, 16 or 20px by size, colored for the step's state. |
| `label` | The step title, medium weight on the current step. In a column, it sits on the indicator's center line. |
| `description` | Optional secondary line under the label. |
| `connector` | The 2px line between two indicators, with a gap at each end; accent once the earlier step is complete. |

## Accessibility

Role: `list`

| Keys | Action |
| --- | --- |
| `Tab` | Moves to the next completed step (a button). The current and upcoming steps are not focusable. |
| `Enter / Space` | Goes back to the focused completed step through onStepSelect. |

- An ordered list. The current step has aria-current="step" and sets data-current.
- A completed step is a button named EN `{label}, completed, go back to this step`, VI `{label}, đã xong, quay lại bước này`.
- Each step's accessible text includes its state word (completed, current, upcoming, error) from statusLabels, not only the icon or color.
- The indicator is hidden from screen readers: the list gives the position and the label gives the state. The connector lines are decorative (aria-hidden).
- Steps with an error show a warning icon on the soft danger fill and the word from statusLabels.error.
- A completed step's button reaches size-target-min in height on touch, through a transparent ::before.

## Install

```bash
npx werewolf-ui add stepper
```

Run `npx werewolf-ui init` once in your app before adding components. Init sets up tokens, their CSS import and agent rules. Add installs this component and its dependencies while preserving your theme. See [Installation](https://werewolf-ui.vercel.app/docs/installation.md) for requirements and the alternative registry setup.