# Stepper

> Source: https://design.nanatec.co.ke/components/stepper/
> A progress trail through a sequence of steps, with an optional linear mode that keeps a wizard from being skipped.

A progress trail through a sequence of steps. The stepper owns which step is
current and which are finished; each step renders the state it is handed.

:::note
This one ships as a web component only. There is no React or Svelte
implementation yet, so the CLI has nothing to copy for those targets.
:::

## Preview

```html
<nana-stepper current="1">
  <nana-stepper-step label="Account">Your details</nana-stepper-step>
  <nana-stepper-step label="Address">Where to send it</nana-stepper-step>
  <nana-stepper-step label="Payment">How to pay</nana-stepper-step>
</nana-stepper>
```

## Installation

```bash
npm install @nana-tec/ui-components
```

```js
import "@nana-tec/ui-components/stepper";
```

## Moving through it

`next()` finishes the step it is on and opens the following one. `previous()`
goes back, and stops at the first. `goTo(index)` jumps, and returns whether the
rules allowed it.

Steps before `current` count as finished. `completed` marks any others, which
matters when a step is finished out of order.

## Linear

Add `linear` and a step only opens once the one before it is finished, so a
wizard cannot be skipped through. A finished step can always be reopened.
Without `linear`, any step can be chosen.

```html
<nana-stepper linear current="0">
  <nana-stepper-step label="Plan">Pick one</nana-stepper-step>
  <nana-stepper-step label="Billing">Locked until the first is done</nana-stepper-step>
  <nana-stepper-step label="Confirm">Locked too</nana-stepper-step>
</nana-stepper>
```

## Vertical

```html
<nana-stepper orientation="vertical" current="1">
  <nana-stepper-step label="Submitted"></nana-stepper-step>
  <nana-stepper-step label="In review"></nana-stepper-step>
  <nana-stepper-step label="Decision"></nana-stepper-step>
</nana-stepper>
```

## Keyboard

| Key | Result |
|---|---|
| <kbd>←</kbd> / <kbd>→</kbd> | Moves focus along a horizontal trail |
| <kbd>↑</kbd> / <kbd>↓</kbd> | Moves focus along a vertical trail |
| <kbd>Home</kbd> / <kbd>End</kbd> | Jumps to the first or last step |
| <kbd>Enter</kbd> / <kbd>Space</kbd> | Opens the focused step, if the rules allow |

Focus moves freely along the trail; only opening a step is governed by `linear`.

## API

## Events

| Event | Type | Description |
|---|---|---|
| `nana-step-change` | `CustomEvent` | The current step moved; `detail` carries `current` and `previous`. |

## Accessibility

The trail is a labelled `group` and each step is a `button` carrying
`aria-current="step"` when it is the one being worked on. A step the rules keep
closed reports `aria-disabled`, and exactly one step stays in the tab order.

## Related components

- [Progress Bar](/components/progress-bar) — a single unlabelled measure
- [Tab Group](/components/tab-group) — switching between panels rather than advancing