---
title: Stepper
description: Guide users through a sequence of panels and completion states.
package: moraine
version: 0.11.0
repository: https://github.com/subframe7536/moraine
---

# Stepper

> Guide users through a sequence of panels and completion states.

## Anatomy

```text
Stepper [component; slot=root]
├── header [slot]
│   └── item [slot]
│       ├── trigger [slot]
│       │   ├── indicator [slot]
│       │   │   └── icon [internal]
│       │   └── wrapper [slot]
│       │       ├── label [slot]
│       │       └── description [slot]
│       └── separator [slot]
└── content [slot]
```

The indicator, label, and description share one trigger; separators appear only between items.

## Usage

Use Stepper to show progress through a fixed sequence of steps. Decide how far users may jump ahead
with `navigation`. Use [Tabs](https://moraine.subf.dev/components/tabs.md) for peer panels that are not a
sequence. Use [Pagination](https://moraine.subf.dev/components/pagination.md) for a result set with a known page count.

```tsx
import { Stepper } from 'moraine'

export function Example() {
  return (
    <Stepper
      items={[
        { value: 'details', label: 'Details' },
        { value: 'review', label: 'Review' },
      ]}
    />
  )
}
```

### Navigation modes

`navigation` (default `'none'`) controls which steps users can activate from their triggers:

- `none` enables only the active step, so the flow moves through your own controls.
- `linear` enables completed steps and the next step, so later steps stay locked until earlier ones
  are reached.
- `free` enables every enabled step.

`onValueChange` fires only when the user activates a different step from a trigger, so in practice
only in `linear` and `free`. It does not fire for programmatic `value` changes. To drive the flow
from your own Previous and Next buttons, control `value` and update it in those handlers. Set
`disabled` on the Stepper to block every trigger.

```tsx
<Stepper items={STEPS} value={step()} onValueChange={setStep} navigation="linear" />
```

### Panels and orientation

Step triggers and panels use tab semantics (`tablist`, `tab`, `tabpanel`). Every item requires a
unique `value`; an item that repeats an earlier value renders disabled and logs a development
warning. `item.content` is static JSX or a component that receives `{ value, index }`; only the
active step's panel renders, and a step without `content` has no panel. Vertical orientation changes
the layout and the arrow keys that move between steps. Stepper marks every step before the active
one as completed, based on item order. Set `item.icon` to replace the step number in the indicator.

```tsx
<Stepper
  defaultValue="details"
  orientation="vertical"
  items={[
    { value: 'details', label: 'Project details', content: () => <ProjectForm /> },
    { value: 'target', label: 'Deploy target', content: () => <TargetForm /> },
  ]}
/>
```

### Keyboard interaction

`activationMode` controls whether arrow-key focus activates a step immediately (`automatic`, the
default) or only moves focus until <kbd>Enter</kbd> or <kbd>Space</kbd> confirms it (`manual`).
Disabled and navigation-locked steps are skipped. Navigation stops at the first and last step unless
you set `loop`.

| Key                                          | Description                                                           |
| -------------------------------------------- | --------------------------------------------------------------------- |
| <kbd>ArrowRight</kbd> / <kbd>ArrowLeft</kbd> | Moves to the next or previous enabled step in horizontal orientation. |
| <kbd>ArrowDown</kbd> / <kbd>ArrowUp</kbd>    | Moves to the next or previous enabled step in vertical orientation.   |
| <kbd>Home</kbd> / <kbd>End</kbd>             | Moves to the first or last enabled step.                              |
| <kbd>Enter</kbd> / <kbd>Space</kbd>          | Activates the focused step in manual activation mode.                 |

## Examples

### Onboard with Previous and Next

Keep the flow linear. Move between Account, Profile, and Review from application buttons.

```tsx
import { Button, Stepper } from 'moraine'
import type { StepperT } from 'moraine'
import { createSignal } from 'solid-js'

const STEPS = [
  { value: 'account', label: 'Account', description: 'User credentials' },
  { value: 'profile', label: 'Profile', description: 'Personal details' },
  { value: 'review', label: 'Review', description: 'Confirmation' },
] satisfies StepperT.Item[]

export function LinearUsage() {
  const [step, setStep] = createSignal('account')
  const stepKeys = ['account', 'profile', 'review']

  const currentIndex = () => stepKeys.indexOf(step())

  const goPrev = () => {
    const prevKey = stepKeys[Math.max(0, currentIndex() - 1)]
    if (prevKey) {
      setStep(prevKey)
    }
  }

  const goNext = () => {
    const nextKey = stepKeys[Math.min(stepKeys.length - 1, currentIndex() + 1)]
    if (nextKey) {
      setStep(nextKey)
    }
  }

  return (
    <div class="max-w-xl w-full space-y-4">
      <Stepper items={STEPS} value={step()} onValueChange={setStep} />
      <div class="flex gap-2">
        <Button size="xs" variant="outline" disabled={currentIndex() === 0} onClick={goPrev}>
          Previous
        </Button>
        <Button size="xs" disabled={currentIndex() === stepKeys.length - 1} onClick={goNext}>
          Next step
        </Button>
      </div>
    </div>
  )
}
```

### One setup panel at a time

Attach content to each step so only the active panel is shown.

```tsx
import { Stepper } from 'moraine'

export function PanelsUsage() {
  return (
    <div class="max-w-md w-full">
      <Stepper
        defaultValue="details"
        items={[
          {
            value: 'details',
            label: 'Project details',
            content: (
              <div class="text-xs text-muted-foreground p-4">
                Configure project name and workspace root.
              </div>
            ),
          },
          {
            value: 'target',
            label: 'Deploy target',
            content: (
              <div class="text-xs text-muted-foreground p-4">
                Select cloud provider and cluster region.
              </div>
            ),
          },
        ]}
      />
    </div>
  )
}
```

### Jump around a release workflow

Control Draft, Review, and Ship from page state with the buttons below.

```tsx
import { Button, Stepper } from 'moraine'
import { createSignal } from 'solid-js'

export function ControlledNonLinear() {
  const RELEASE_STEPS = () => [
    {
      label: 'Draft',
      value: 'draft',
      content: <p class="text-sm text-foreground">Prepare release notes.</p>,
    },
    {
      label: 'Review',
      value: 'review',
      content: <p class="text-sm text-foreground">Collect team approvals.</p>,
    },
    {
      label: 'Ship',
      value: 'ship',
      content: <p class="text-sm text-foreground">Deploy to production.</p>,
    },
  ]

  const [releaseStep, setReleaseStep] = createSignal('review')

  return (
    <div class="space-y-4">
      <Stepper items={RELEASE_STEPS()} value={releaseStep()} onValueChange={setReleaseStep} />
      <div class="flex flex-wrap gap-2 items-center">
        <Button size="sm" variant="outline" onClick={() => setReleaseStep('draft')}>
          Go to draft
        </Button>
        <Button size="sm" variant="outline" onClick={() => setReleaseStep('review')}>
          Go to review
        </Button>
        <Button size="sm" variant="outline" onClick={() => setReleaseStep('ship')}>
          Go to ship
        </Button>
        <p class="text-xs text-muted-foreground">Current step: {releaseStep()}</p>
      </div>
    </div>
  )
}
```

### Compare navigation modes

Choose a `navigation` mode to see which checkout steps can be activated.

```tsx
import { Button, Stepper } from 'moraine'
import type { StepperT } from 'moraine'
import { For, createSignal } from 'solid-js'

type Navigation = NonNullable<StepperT.Base['navigation']>

const NAVIGATION_MODES: Navigation[] = ['none', 'linear', 'free']

export function NavigationModes() {
  const [navigation, setNavigation] = createSignal<Navigation>('linear')
  const checkoutSteps = [
    {
      label: 'Address',
      description: 'Where should we send the order?',
      icon: 'i-lucide:map-pinned',
      value: 'address',
      content: <p class="text-sm text-foreground">Collect shipping address details.</p>,
    },
    {
      label: 'Shipping',
      description: 'Choose a delivery method.',
      icon: 'i-lucide:truck',
      value: 'shipping',
      content: <p class="text-sm text-foreground">Pick standard, express, or local pickup.</p>,
    },
    {
      label: 'Payment',
      description: 'Confirm billing and payment.',
      icon: 'i-lucide:credit-card',
      value: 'payment',
      content: <p class="text-sm text-foreground">Review billing details and submit payment.</p>,
    },
  ] satisfies StepperT.Item[]

  return (
    <div class="space-y-4">
      <div class="flex flex-wrap gap-2">
        <For each={NAVIGATION_MODES}>
          {(mode) => (
            <Button
              size="xs"
              variant={navigation() === mode ? 'solid' : 'outline'}
              onClick={() => setNavigation(mode)}
            >
              {mode}
            </Button>
          )}
        </For>
      </div>

      <Stepper items={checkoutSteps} defaultValue="address" navigation={navigation()} />
    </div>
  )
}
```

## API Reference

### Attributes

| Attributes | Slot | Description |
| --- | --- | --- |
| `data-disabled` | `stepper-item`, `stepper-separator` | Present when the component, slot, or item is disabled. |
| `data-state` | `stepper-item`, `stepper-trigger`, `stepper-indicator`, `stepper-separator` | Stores the component state used by styling hooks (e.g. open, closed, active). |
| `data-clickable` | `stepper-trigger` | Present when the step or item accepts direct activation. |
| `data-selected` | `stepper-trigger`, `stepper-content` | Present when the item or tab is selected. |

### Props

Props for the Stepper component.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| activationMode | 'automatic' \| 'manual' \| undefined | 'automatic' | Whether arrow-key focus movement activates the step immediately (`automatic`) or only moves<br>focus until `Enter` or `Space` confirms it (`manual`). |
| defaultValue | Value \| undefined | — | Initially active step value for uncontrolled usage. The first enabled step is active when omitted. |
| disabled | boolean \| undefined | false | Whether the entire stepper is disabled: no step can be activated by click or keyboard. |
| id | string \| undefined | — | DOM `id` of the stepper root element; the trigger and panel ids derive from it. Generated when omitted. |
| items | ({<br>  /** Unique value identifying the step in `value` and `onValueChange`. A step that repeats an<br>earlier step's value is disabled. */<br>  value: Value;<br>  /** Label of the step. It names the step trigger for assistive technology. */<br>  label?: JSX.Element;<br>  /** Secondary description of the step, shown with the label and used as the trigger's accessible description. */<br>  description?: JSX.Element;<br>  /** Icon to display in the step indicator instead of the step number. */<br>  icon?: IconT.Name;<br>  /** Content to display in the panel below the steps while this step is active. Accepts static JSX<br>or a component receiving `{ value, index }`. A step without `content` renders no panel. */<br>  content?: JSX.Element \| Component<ContentRenderProps>;<br>  /** Whether the step is disabled. */<br>  disabled?: boolean;<br>  /** Additional class name for this step's item element, merged after the slot classes. */<br>  class?: string;<br>})[] \| undefined | — | Array of steps to display, in order. |
| loop | boolean \| undefined | false | Whether arrow-key navigation wraps from the last step to the first and back. Disabled steps are skipped. |
| navigation | 'none' \| 'linear' \| 'free' \| undefined | 'none' | How users move between steps. `none` keeps only the active step enabled, `linear` also allows<br>completed steps and the next step, and `free` allows every enabled step. |
| onValueChange | ((value: Value) => void) \| undefined | — | Called with the step's `value` when the user activates a different step by click or keyboard.<br>It does not fire for programmatic `value` changes, for the already-active step, or while the<br>stepper is `disabled`. |
| orientation | 'horizontal' \| 'vertical' \| undefined | 'horizontal' | Direction in which steps are laid out. It also decides which arrow keys move between steps. |
| size | 'sm' \| 'md' \| 'lg' \| undefined | 'md' | Visual size of the component. |
| value | Value \| undefined | — | Controlled active step value. When `undefined`, or when it matches no enabled step, the first enabled step is active.<br>Steps before the active one are marked completed. |
| class | SlotClassValue \| undefined | — | Class applied to the component root or trigger element. |
| classes | Classes \| undefined | — | Family slot class defaults for this instance. |
| style | SlotStyleValue \| undefined | — | Style applied to the component root or trigger element. |
| styles | Styles \| undefined | — | Family slot style defaults for this instance. |

**`items` example**

```tsx
import { Stepper } from 'moraine'

<Stepper
  navigation="free"
  items={[
    { value: 'cart', label: 'Cart', description: '2 items' },
    { value: 'shipping', label: 'Shipping', icon: 'icon-truck' },
    { value: 'payment', label: 'Payment', disabled: true },
  ]}
/>
```
