# Stepper

Shows how far the user is through a fixed number of steps: a label, the current step over the total, and one segment per step. Steps are 1-based; `value` and `max` floor to whole numbers of at least 1, and `value` clamps to `max`.

## Use for

- progress through a multi-step flow, such as step 2 of 3
- segments that jump back to an earlier step

## Practices

- Do: Pass localized `label`, `countLabel` and `stepLabel`. The defaults are English.
- Do: Keep the current step in the flow's machine and pass it as `value`. See Multi-step flows (`mosaic guides inspect controllers`).

## API reference

### Stepper

Renders a `div` with the text (`cl-stepper-text`, holding `cl-stepper-label` and `cl-stepper-count`) and the segments (`cl-stepper-segments`). Each segment is a `cl-stepper-segment` with `data-state` of `complete`, `current` or `upcoming`. Carries `data-value` and `data-max`.

Slot: `cl-stepper`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` |  | The current step, from 1. |
| `max` | `number` |  | The number of steps. |
| `onValueChange` | `(value: number) => void` |  | Makes each segment a button that calls this with its step. The current one gets `aria-current='step'`. Without it the segments are `aria-hidden`. |
| `label` | `string` | `'Step'` | Text before the count. |
| `countLabel` | `string` | `'{step} of {total}'` | The count, with `{step}` and `{total}` filled in. |
| `stepLabel` | `string` | `'Step {step}'` | Each segment button's accessible name, with `{step}` filled in. |

## Examples

### Read-only

```tsx
<Stepper value={1} max={3} />
```

### Navigable

```tsx
<Stepper value={step} max={3} onValueChange={setStep} />
```

## Related

- [Flow](/docs/components/flow.md)
