# Stepper

Shows progress through a fixed sequence of steps.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Stepper.tsx)

Figma: [Controls/Stepper](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-1489) (`Stepper.Root`)

## Overview

A stepper renders the steps as a row of 24px segments, 4px apart. Pass `aria-label` to name the flow, such as Account setup.

## Examples

### Basic

```tsx
import { Stepper, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return <Stepper.Root aria-label="Account setup" count={3} value={1} {...styles.stepper()} />
}

namespace styles {
  export const stepper = style({ maxWidth: '24rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Stepper/Basic.tsx)

### Value

Set `count` to the number of steps and `value` to the current step, from `1` to `count`.

```tsx
import { Stepper, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <div {...styles.stack()}>
      {[1, 2, 3].map((value) => (
        <Stepper.Root aria-label="Account setup" count={3} key={value} value={value} />
      ))}
    </div>
  )
}

namespace styles {
  export const stack = style({
    display: 'flex',
    flexDirection: 'column',
    gap: '16',
    maxWidth: '24rem !custom',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Stepper/Value.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { Stepper } from '@tempoxyz/ds'

<Stepper.Root />
```

## Guidelines

### When to Use

* Show a multi-step flow with a fixed number of steps, such as onboarding (Create passkey, Back up, Add funds) or a send flow (Recipient, Amount, Review).
* Split one long setup form into short screens, such as business verification before API key access.

### When Not to Use

* Use [Progress](/docs/components/progress) for measurable work, such as a file upload or a sync to the latest block.
* Use [Tabs](/docs/components/tabs) for sections in any order. A stepper is not interactive, and its segments don't link to steps.
* Use [Breadcrumbs](/docs/components/breadcrumbs) to show where a page sits in the hierarchy.
* Use one form, laid out with [Field](/docs/components/field) and [Fieldset](/docs/components/fieldset), when the task fits on one screen.

### Keep the Step Count Fixed

Set `count` once for the whole flow, and aim for three to five steps. Merge short steps before you add segments. If an answer skips a step, keep its segment and move past it.

**Do:** Keep the same total on every step.

```tsx
/** Do example for "Keep the Step Count Fixed" on the Stepper page: keep the same total on every step. @module */
import { Stepper, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.flow()}>
      <div {...styles.screen()}>
        <Stepper.Root aria-label="Account setup" count={4} value={1} />
        <span {...styles.step()}>Step 1 of 4</span>
      </div>
      <div {...styles.screen()}>
        <Stepper.Root aria-label="Account setup" count={4} value={2} />
        <span {...styles.step()}>Step 2 of 4</span>
      </div>
    </div>
  )
}

namespace styles {
  export const flow = style({
    display: 'flex',
    flexDirection: 'column',
    rowGap: '24',
    width: '100% !custom',
  })

  export const screen = style({ display: 'flex', flexDirection: 'column', rowGap: '8' })

  export const step = style({ color: 'content.secondary', typography: 'body.b3' })
}
```

**Don't:** Change the total partway, which makes the progress look wrong.

```tsx
/**
 * Don't example for "Keep the Step Count Fixed" on the Stepper page.
 * Don't change the total partway, which makes the progress look wrong.
 * @module
 */
import { Stepper, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.flow()}>
      <div {...styles.screen()}>
        <Stepper.Root aria-label="Account setup" count={3} value={1} />
        <span {...styles.step()}>Step 1 of 3</span>
      </div>
      <div {...styles.screen()}>
        <Stepper.Root aria-label="Account setup" count={5} value={2} />
        <span {...styles.step()}>Step 2 of 5</span>
      </div>
    </div>
  )
}

namespace styles {
  export const flow = style({
    display: 'flex',
    flexDirection: 'column',
    rowGap: '24',
    width: '100% !custom',
  })

  export const screen = style({ display: 'flex', flexDirection: 'column', rowGap: '8' })

  export const step = style({ color: 'content.secondary', typography: 'body.b3' })
}
```

### Label the Current Step in Text

The segments carry no text. Place a visible step number and a heading above the stepper, such as Step 2 of 3 above Enter amount.

**Do:** Pair the stepper with the step number and the step's title.

```tsx
/**
 * Do example for "Label the Current Step in Text" on the Stepper page.
 * Pair the stepper with the step number and the step's title.
 * @module
 */
import { Stepper, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.flow()}>
      <Stepper.Root aria-label="Send payment" count={3} value={2} />
      <span {...styles.step()}>Step 2 of 3</span>
      <span {...styles.title()}>Enter amount</span>
    </div>
  )
}

namespace styles {
  export const flow = style({
    display: 'flex',
    flexDirection: 'column',
    rowGap: '8',
    width: '100% !custom',
  })

  export const step = style({
    color: 'content.secondary',
    marginBlockStart: '8',
    typography: 'body.b3',
  })

  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
}
```

**Don't:** Show the segments without any text.

```tsx
/**
 * Don't example for "Label the Current Step in Text" on the Stepper page.
 * Don't show the segments without any text.
 * @module
 */
import { Stepper, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.flow()}>
      <Stepper.Root count={3} value={2} />
    </div>
  )
}

namespace styles {
  export const flow = style({ width: '100% !custom' })
}
```

### Let People Go Back

Give every step after the first a Back button before the primary action, and keep the values already entered. Make the last step a review with a specific primary action, such as Confirm payment, and set `value` to `count` there.

**Do:** Offer Back before the primary action.

```tsx
/** Do example for "Let People Go Back" on the Stepper page: offer Back before the primary action. @module */
import { Button, Stepper, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.flow()}>
      <Stepper.Root aria-label="Send payment" count={3} value={2} />
      <span {...styles.step()}>Step 2 of 3</span>
      <span {...styles.title()}>Enter amount</span>
      <div {...styles.actions()}>
        <Button variant="secondary">Back</Button>
        <Button>Continue</Button>
      </div>
    </div>
  )
}

namespace styles {
  export const actions = style({
    columnGap: '8',
    display: 'flex',
    justifyContent: 'flex-end',
    marginBlockStart: '16',
  })

  export const flow = style({
    display: 'flex',
    flexDirection: 'column',
    rowGap: '8',
    width: '100% !custom',
  })

  export const step = style({
    color: 'content.secondary',
    marginBlockStart: '8',
    typography: 'body.b3',
  })

  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
}
```

**Don't:** Leave a step with only a way forward.

```tsx
/**
 * Don't example for "Let People Go Back" on the Stepper page.
 * Don't leave a step with only a way forward.
 * @module
 */
import { Button, Stepper, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.flow()}>
      <Stepper.Root aria-label="Send payment" count={3} value={2} />
      <span {...styles.step()}>Step 2 of 3</span>
      <span {...styles.title()}>Enter amount</span>
      <div {...styles.actions()}>
        <Button>Continue</Button>
      </div>
    </div>
  )
}

namespace styles {
  export const actions = style({
    columnGap: '8',
    display: 'flex',
    justifyContent: 'flex-end',
    marginBlockStart: '16',
  })

  export const flow = style({
    display: 'flex',
    flexDirection: 'column',
    rowGap: '8',
    width: '100% !custom',
  })

  export const step = style({
    color: 'content.secondary',
    marginBlockStart: '8',
    typography: 'body.b3',
  })

  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
}
```

### Keep It in One Place

Place the stepper in the same spot on every step. In a [Dialog](/docs/components/dialog) or a [Frame](/docs/components/frame), center it in the header, with the Back button on the left from the second step.

**Do:** Place the stepper at the top, above the step's heading.

```tsx
/**
 * Do example for "Label the Current Step in Text" on the Stepper page.
 * Pair the stepper with the step number and the step's title.
 * @module
 */
import { Stepper, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.flow()}>
      <Stepper.Root aria-label="Send payment" count={3} value={2} />
      <span {...styles.step()}>Step 2 of 3</span>
      <span {...styles.title()}>Enter amount</span>
    </div>
  )
}

namespace styles {
  export const flow = style({
    display: 'flex',
    flexDirection: 'column',
    rowGap: '8',
    width: '100% !custom',
  })

  export const step = style({
    color: 'content.secondary',
    marginBlockStart: '8',
    typography: 'body.b3',
  })

  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
}
```

**Don't:** Place the stepper below the step's content.

```tsx
/**
 * Don't example for "Keep It in One Place" on the Stepper page.
 * Don't place the stepper below the step's content.
 * @module
 */
import { Stepper, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.flow()}>
      <span {...styles.step()}>Step 2 of 3</span>
      <span {...styles.title()}>Enter amount</span>
      <Stepper.Root aria-label="Send payment" count={3} value={2} {...styles.stepper()} />
    </div>
  )
}

namespace styles {
  export const flow = style({
    display: 'flex',
    flexDirection: 'column',
    rowGap: '8',
    width: '100% !custom',
  })

  export const step = style({ color: 'content.secondary', typography: 'body.b3' })

  export const stepper = style({ marginBlockStart: '16' })

  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
}
```

## Content

* Write step titles as short tasks or nouns, such as Recipient, Amount, and Review.
* Match the visible step text to the announced value, Step 2 of 3.
* Before the first step, list what people need, such as an ID or a funded wallet.

## Accessibility

A stepper renders a `progressbar` whose value is the current step. The segments are visual only.

### Semantics

* **Root (progressbar):** Its value is the current step, 1 to `count`.
* **Value Text (aria-valuetext):** Reads as "Step 2 of 4".
* **Name (aria-label):** Named "Progress" by default.
* **No Focus Stop (not focusable):** Tab moves past it to the next control.

### Your Responsibilities

* **Name the Flow (aria-label):** Name the flow, such as "Account setup". Don't repeat the step text, which is already read.
* **Label Each Step (SC 1.3.1):** Name the current step in visible text, so progress doesn't rely on color alone.
* **Move Focus on Advance:** When the step changes, move focus to the new step's heading, so screen readers announce the new step.

## Related

[Progress](/docs/components/progress)

Use for measurable work.

[Dialog](/docs/components/dialog)

Use for flows that open over the page.

[Forms](/docs/patterns/forms)

Covers laying out each step.

[Payments](/docs/patterns/payments)

Covers send and review flows.
