# 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.

## Cách dùng

### Khi nào dùng

- 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.

### Khi nào không dùng

- 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.

## Biến thể

### 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.

Giá trị: `horizontal`, `vertical`. Mặc định: `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.

Giá trị: `sm`, `md`, `lg`. Mặc định: `md`.

## Ví dụ

### 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} />
```

## Nên và không nên

### Nên

- 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.

### Không nên

- 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

| Tên | Kiểu | Giá trị | Mặc định | Mô tả |
| --- | --- | --- | --- | --- |
| `steps` (bắt buộc) | `{ 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` (bắt buộc) | `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`. |

### Slot

| Tên | Bắt buộc | Mô tả |
| --- | --- | --- |
| `stepIcon` | không | 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. |

## Cấu tạo

| Phần | Mô tả |
| --- | --- |
| `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. |

## Khả năng truy cập

Role: `list`

| Phím | Hành động |
| --- | --- |
| `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.

## Cài đặt

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

Chạy `npx werewolf-ui init` một lần trong app trước khi thêm component. Init cài token, thêm CSS import và luật cho agent. Add cài component này cùng các dependency và giữ nguyên theme của bạn. Xem [Cài đặt](https://werewolf-ui.vercel.app/vi/docs/installation.md) để biết yêu cầu và cách cài qua registry.