# Stepper

> Shows progress through an ordered, multi-step task.

Category: Navigation · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/stepper

Use Stepper for flows that must be completed in order, such as creating a signature: choose a template, add details, assign users, deploy. Steps before the active one are complete; mark a step with status="error" when it needs attention. Pass onStepClick to let people return to completed steps.

## Import

```tsx
import { Stepper, Step } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### Basic

```tsx
import { Step, Stepper } from '@bindshq/stance-react';

export function Basic() {
  return (
    <Stepper activeStep={2} style={{ width: '100%' }}>
      <Step title="Choose template" />
      <Step title="Add details" />
      <Step title="Assign users" />
      <Step title="Deploy" />
    </Stepper>
  );
}
```

### Clickable steps

Completed steps become buttons that jump back.

```tsx
import { useState } from 'react';
import { Button, Step, Stepper } from '@bindshq/stance-react';

export function Interactive() {
  const [step, setStep] = useState(2);
  return (
    <div style={{ display: 'grid', gap: 24, width: '100%' }}>
      <Stepper activeStep={step} onStepClick={setStep}>
        <Step title="Template" />
        <Step title="Details" />
        <Step title="Users" />
        <Step title="Deploy" />
      </Stepper>
      <div style={{ display: 'flex', gap: 8 }}>
        <Button variant="outline" disabled={step === 0} onClick={() => setStep((s) => s - 1)}>
          Back
        </Button>
        <Button disabled={step === 3} onClick={() => setStep((s) => s + 1)}>
          Continue
        </Button>
      </div>
    </div>
  );
}
```

### Vertical with descriptions

```tsx
import { Step, Stepper } from '@bindshq/stance-react';

export function Vertical() {
  return (
    <Stepper activeStep={1} orientation="vertical">
      <Step title="Connect Exchange" description="Relay connector verified" />
      <Step title="Sync users" description="Importing 214 users from Azure AD" />
      <Step title="Assign templates" description="Choose a signature per team" />
      <Step title="Go live" description="Signatures apply to outgoing mail" />
    </Stepper>
  );
}
```

### Error state

```tsx
import { Step, Stepper } from '@bindshq/stance-react';

export function WithError() {
  return (
    <Stepper activeStep={2} style={{ width: '100%' }}>
      <Step title="Upload spreadsheet" />
      <Step title="Map columns" status="error" description="2 columns unmapped" />
      <Step title="Review" />
      <Step title="Import" />
    </Stepper>
  );
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Stepper | `activeStep` (required) | `number` | None | Zero-based index of the current step. |
| Stepper | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Horizontal steppers stack below 640px. |
| Stepper | `onStepClick` | `(index: number) => void` | None | Makes completed steps clickable. |
| Stepper | `allowFutureSteps` | `boolean` | `false` | Also allow clicking upcoming steps. |
| Stepper | `aria-label` | `string` | `'Progress'` | Name of the list. |
| Stepper | `labels` | `Partial<StepperLabels>` | None | Translatable status words and “Step x of y”. |
| Step | `title` (required) | `ReactNode` | None | Step name. |
| Step | `description` | `ReactNode` | None | Supporting text. |
| Step | `status` | `'complete' \| 'current' \| 'upcoming' \| 'error'` | None | Overrides the derived status. |
| Step | `icon` | `ReactNode` | None | Custom indicator content. |
| Step | `disabled` | `boolean` | None | Prevents clicking this step. |

## Accessibility

- An ordered list; the current step has aria-current="step".
- Each step announces its position and status, e.g. “Assign users, Step 3 of 4, Current step”, so meaning never depends on colour or icons.
- Clickable steps are real buttons; non-clickable steps are not focusable.

## Keyboard

| Keys | Action |
| --- | --- |
| `Tab` | Moves between clickable steps. |
| `Enter` `Space` | Returns to the step. |

## Guidelines

**Do**

- Keep to between three and seven steps.
- Use short noun or verb phrases.

**Don’t**

- Use for navigation between unrelated pages.
- Let people skip required steps.

## Related

- https://stanceui.com/components/tabs
- https://stanceui.com/components/progress