LayoutReact

Stepper

The steps of a process, one shown at a time, with the current step marked and the steps before it completed.

Rendered by React 19.3.1

Loading React…

import { Stepper } from '@hamur/react/stepper'

const steps = [
  { value: 'address', title: 'Address', body: 'Ship to 12 Analytical Row, London.' },
  { value: 'shipping', title: 'Shipping', body: 'Standard delivery, three to five days.' },
  { value: 'payment', title: 'Payment', body: 'Pay with the card ending in 4242.' },
]

export default function StepperExample() {
  return (
    <Stepper.Root className="stepper" defaultValue="address">
      <Stepper.List className="stepper-list" aria-label="Checkout">
        {steps.map((step, index) => (
          <Stepper.Item
            key={step.value}
            value={step.value}
            className="stepper-item"
          >
            <Stepper.Trigger className="stepper-trigger">
              <Stepper.Indicator className="stepper-indicator" />
              <Stepper.Title className="stepper-title">
                {step.title}
              </Stepper.Title>
            </Stepper.Trigger>
            {index < steps.length - 1 ? (
              <Stepper.Separator className="stepper-separator" />
            ) : null}
          </Stepper.Item>
        ))}
      </Stepper.List>
      {steps.map((step) => (
        <Stepper.Panel
          key={step.value}
          value={step.value}
          className="stepper-panel"
        >
          {step.body}
        </Stepper.Panel>
      ))}
      <div className="stepper-nav">
        <Stepper.Previous className="button">
          Back
        </Stepper.Previous>
        <Stepper.Value className="stepper-value" />
        <Stepper.Next className="button">
          Continue
        </Stepper.Next>
      </div>
    </Stepper.Root>
  )
}

Not measured yetTests passing in React

Not measured yetSize

Not measured yetMemory

Not measured yetSpeed

[N] commits

Installation

npm i @hamur/react

Not on npm yet. The package goes out under the chosen name.

Anatomy

Import the component and assemble its parts:

<Stepper.Root>
  <Stepper.List>
    <Stepper.Item>
      <Stepper.Trigger>
        <Stepper.Indicator />
        <Stepper.Title />
      </Stepper.Trigger>
      <Stepper.Separator />
    </Stepper.Item>
  </Stepper.List>
  <Stepper.Panel />
  <Stepper.Previous />
  <Stepper.Value />
  <Stepper.Next />
</Stepper.Root>

// Not in this example: Stepper.Description

Examples

Tabs

pattern="tabs" with linear={false}: four steps of a new project, one optional, moved between with the arrow keys; the controlled value is shown below.

StepperTabs.tsx

import * as React from 'react'
import { Stepper } from '@hamur/react/stepper'

const steps = [
  { value: 'details', title: 'Details', body: 'Name the project and pick its region.' },
  { value: 'team', title: 'Team', body: 'Invite the people who will work on it.' },
  { value: 'billing', title: 'Billing', body: 'Add a card now or later.', optional: true },
  { value: 'review', title: 'Review', body: 'Check the settings and create the project.' },
]

export default function StepperTabsExample() {
  const [value, setValue] = React.useState('details')
  return (
    <div className="stack">
      <Stepper.Root
        className="stepper"
        pattern="tabs"
        linear={false}
        value={value}
        onValueChange={setValue}
      >
        <Stepper.List className="stepper-list" aria-label="New project">
          {steps.map((step, index) => (
            <Stepper.Item
              key={step.value}
              value={step.value}
              optional={step.optional}
              className="stepper-item"
            >
              <Stepper.Trigger className="stepper-trigger">
                <Stepper.Indicator className="stepper-indicator" />
                <Stepper.Title className="stepper-title">
                  {step.title}
                </Stepper.Title>
              </Stepper.Trigger>
              {index < steps.length - 1 ? (
                <Stepper.Separator className="stepper-separator" />
              ) : null}
            </Stepper.Item>
          ))}
        </Stepper.List>
        {steps.map((step) => (
          <Stepper.Panel
            key={step.value}
            value={step.value}
            className="stepper-panel"
          >
            {step.body}
          </Stepper.Panel>
        ))}
        <div className="stepper-nav">
          <Stepper.Previous className="button">
            Back
          </Stepper.Previous>
          <Stepper.Next className="button">
            Continue
          </Stepper.Next>
        </div>
      </Stepper.Root>
      <p className="muted">Current step: {value}</p>
    </div>
  )
}

Form

A sign-up inside a Form: Next refuses a step while its required field is empty and focuses it, and the last step submits every step's values.

StepperForm.tsx

import * as React from 'react'
import { Field } from '@hamur/react/field'
import { Form } from '@hamur/react/form'
import { Stepper } from '@hamur/react/stepper'

const steps = [
  { value: 'account', title: 'Account' },
  { value: 'profile', title: 'Profile' },
  { value: 'confirm', title: 'Confirm' },
]

export default function StepperFormExample() {
  const [created, setCreated] = React.useState('')
  return (
    <Form
      className="stack"
      onFormSubmit={(values) => setCreated(`Created an account for ${String(values.email)}`)}
    >
      <Stepper.Root className="stepper" defaultValue="account">
        <Stepper.List className="stepper-list" aria-label="Sign up">
          {steps.map((step, index) => (
            <Stepper.Item
              key={step.value}
              value={step.value}
              className="stepper-item"
            >
              <Stepper.Trigger className="stepper-trigger">
                <Stepper.Indicator className="stepper-indicator" />
                <Stepper.Title className="stepper-title">
                  {step.title}
                </Stepper.Title>
              </Stepper.Trigger>
              {index < steps.length - 1 ? (
                <Stepper.Separator className="stepper-separator" />
              ) : null}
            </Stepper.Item>
          ))}
        </Stepper.List>
        <Stepper.Panel value="account" className="stepper-panel">
          <Field.Root name="email" className="field">
            <Field.Label>Email</Field.Label>
            <Field.Control type="email" className="input" required placeholder="ada@example.com" />
            <Field.Error className="error" />
          </Field.Root>
        </Stepper.Panel>
        <Stepper.Panel value="profile" className="stepper-panel">
          <Field.Root name="name" className="field">
            <Field.Label>Name</Field.Label>
            <Field.Control className="input" required placeholder="Ada Lovelace" />
            <Field.Error className="error" />
          </Field.Root>
        </Stepper.Panel>
        <Stepper.Panel value="confirm" className="stepper-panel">
          <div className="stack">
            <p className="stepper-note">Check your details, then create the account.</p>
            <button className="button" type="submit">
              Create account
            </button>
          </div>
        </Stepper.Panel>
        <div className="stepper-nav">
          <Stepper.Previous className="button">
            Back
          </Stepper.Previous>
          <Stepper.Value className="stepper-value" />
          <Stepper.Next className="button">
            Continue
          </Stepper.Next>
        </div>
      </Stepper.Root>
      {created ? <p className="muted">{created}</p> : null}
    </Form>
  )
}

Vertical

orientation="vertical": each step's panel under its title, with a Description and Back and Continue inside the panel; the last step is optional.

StepperVertical.tsx

import { Stepper } from '@hamur/react/stepper'

const steps = [
  {
    value: 'repository',
    title: 'Create a repository',
    description: 'Name it and choose who can see it',
    body: 'A public repository named analytical-engine.',
  },
  {
    value: 'readme',
    title: 'Add a README',
    description: 'Say what the project does',
    body: 'A README with a title and one paragraph.',
  },
  {
    value: 'collaborators',
    title: 'Invite collaborators',
    description: 'You can do this later',
    body: 'No one invited yet.',
    optional: true,
  },
]

export default function StepperVerticalExample() {
  return (
    <Stepper.Root
      className="stepper"
      orientation="vertical"
      defaultValue="repository"
    >
      <Stepper.List className="stepper-list" aria-label="New repository">
        {steps.map((step, index) => (
          <Stepper.Item
            key={step.value}
            value={step.value}
            optional={step.optional}
            className="stepper-item"
          >
            <Stepper.Trigger className="stepper-trigger">
              <Stepper.Indicator className="stepper-indicator" />
              <span className="stepper-text">
                <Stepper.Title className="stepper-title">
                  {step.title}
                </Stepper.Title>
                <Stepper.Description className="stepper-description">
                  {step.description}
                </Stepper.Description>
              </span>
            </Stepper.Trigger>
            {index < steps.length - 1 ? (
              <Stepper.Separator className="stepper-separator" />
            ) : null}
            <Stepper.Panel value={step.value} className="stepper-panel">
              <p className="stepper-note">{step.body}</p>
              <div className="stepper-nav">
                {index > 0 ? (
                  <Stepper.Previous className="button">
                    Back
                  </Stepper.Previous>
                ) : null}
                {index < steps.length - 1 ? (
                  <Stepper.Next className="button">
                    Continue
                  </Stepper.Next>
                ) : null}
              </div>
            </Stepper.Panel>
          </Stepper.Item>
        ))}
      </Stepper.List>
    </Stepper.Root>
  )
}

API reference

27 props across 12 parts, in React syntax. className, style, render are listed once, under Shared props.

Description`Stepper.Description`

A description of the step, which describes its Trigger. Renders a <span>.

Indicator`Stepper.Indicator`

The step's marker, hidden from assistive technology. Shows the step's 1-based position unless it has children. Renders a <span>.

Item`Stepper.Item`

A step of the process: its Trigger, Indicator, Title, Description and Separator, and in pattern="list" its Panel too. Renders a <li>.

Item props
Prop	Type	Default
`value`requiredThe value of the step.	`any`	`—`
`disabled`Whether the step cannot be activated.	`boolean`	`false`
`optional`Whether the step does not block reaching the steps after it.	`boolean`	`false`
`completed`Whether the step is completed, overriding the state the Root tracks.	`boolean`	`—`
`invalid`Whether the step has errors: it shows the error state and, with `linear`, refuses a forward	`boolean`	`—`
`label`The step's name in announcements.	`string`	`—`

Item data attributes
Data attribute	Description
`data-index`	The 0-based position of the step.
`data-current`	Present when the step is the current one.
`data-completed`	Present when the step is completed.
`data-invalid`	Present when the step has errors.
`data-optional`	Present when the step is optional.
`data-disabled`	Present when the step is disabled.
`data-unreachable`	Present when the step cannot be reached yet.
`data-orientation`	Indicates the orientation of the stepper.

List`Stepper.List`

The list of steps: an ordered list, or the tablist in pattern="tabs". Renders an <ol>.

Next`Stepper.Next`

Goes to the next enabled step, validating the current one with linear. It is never a submit button, and is aria-disabled, not disabled, at the last enabled step. Renders a <button>.

Next props
Prop	Type	Default
`nativeButton`Whether the component renders a native `<button>` element when replacing it	`boolean`	`true`
`focusableWhenDisabled`Whether the button stays focusable while it is disabled, with `aria-disabled`.	`boolean`	`true`

Panel`Stepper.Panel`

The content of a step, shown while it is current: a group in pattern="list", a tabpanel in pattern="tabs", labelled by the step's Title. Renders a <div>.

Panel props
Prop	Type	Default
`value`requiredThe value of the step this panel belongs to.	`any`	`—`
`keepMounted`Whether to keep the element in the DOM while the step is not current, so its fields keep	`boolean`	`true`
`initialFocus`The element to focus when a move made from inside the stepper shows this panel.	`boolean \| React.RefObject<HTMLElement \| null> \| (() => boolean \| void \| HTMLElement \| null)`	`true`

Panel data attributes
Data attribute	Description
`data-index`	The 0-based position of the panel's step.
`data-hidden`	Present when the panel is hidden.
`data-current`	Present when the panel's step is the current one.
`data-completed`	Present when the panel's step is completed.
`data-invalid`	Present when the panel's step has errors.
`data-orientation`	Indicates the orientation of the stepper.
`data-activation-direction`	Indicates the direction of the last step change.
`data-starting-style`	Present when the panel begins animating in.
`data-ending-style`	Present when the panel is animating out.

Previous`Stepper.Previous`

Goes to the previous enabled step, without validating. It is aria-disabled, not disabled, at the first enabled step, so it keeps focus. Renders a <button>.

Previous props
Prop	Type	Default
`nativeButton`Whether the component renders a native `<button>` element when replacing it	`boolean`	`true`
`focusableWhenDisabled`Whether the button stays focusable while it is disabled, with `aria-disabled`.	`boolean`	`true`

Root`Stepper.Root`

Groups all parts of the stepper: the steps of a process, their panels and the Previous and Next buttons., followed by the status region. Renders a <div>.

Root props
Prop	Type	Default
`value`The value of the current step.	`any`	`—`
`defaultValue`The value of the step that is current when the stepper is first rendered.	`any`	`0`
`onValueChange`Event handler called before the current step changes.	`((value: any, eventDetails: StepperRootChangeEventDetails) => void)`	`—`
`pattern`The pattern of the stepper.	`StepperPattern`	`'list'`
`linear`Whether a forward move validates the current step and is refused while it is invalid, and a	`boolean`	`true`
`orientation`The orientation of the step list.	`StepperOrientation`	`'horizontal'`
`loopFocus'tabs'` only: whether the arrow keys wrap at the ends of the list.	`boolean`	`false`
`disabled`Whether the component should ignore user interaction.	`boolean`	`false`
`getStepHref'list'` only: the `href` of each step.	`((value: any) => string)`	`—`
`actionsRef`A ref to move and validate from the app.	`React.RefObject<StepperRootActions \| null>`	`—`
`labels`The texts of the status region, the `Value` part and the state of each Title.	`Partial<StepperLabels>`	`—`

Root data attributes
Data attribute	Description
`data-orientation`	Indicates the orientation of the stepper.
`data-pattern`	Indicates the pattern of the stepper.
`data-linear`	Present when a forward move validates the current step.
`data-disabled`	Present when the stepper is disabled.

Separator`Stepper.Separator`

The line between steps, hidden from assistive technology and styled by its step's state. Renders a <div>.

Title`Stepper.Title`

The step's name: it names the Trigger and the Panel, and ends with a visually hidden text of the step's state (completed, error, optional). Renders a <span>.

Trigger`Stepper.Trigger`

Activates its step and is named by the step's Title: a button, a tab in pattern="tabs", or a link when the Root has getStepHref., or an <a> element with getStepHref. Renders a <button>.

Trigger props
Prop	Type	Default
`nativeButton`Whether the component renders a native `<button>` element when replacing it	`boolean`	`true`
`focusableWhenDisabled`Whether the Trigger stays focusable while its step is disabled or cannot be reached, with	`boolean`	`true`

Value`Stepper.Value`

The current step's position as text: "Step 2 of 4". Plain text, not a live region. Renders a <span>.

Value props
Prop	Type	Default
`children`The text, or a function of the current step's position, the number of steps, its value and	`React.ReactNode \| ((values: StepperValueValues) => React.ReactNode)`	`—`

Shared props

Every part that renders an element takes these.

Shared props
Prop	Type
`className`CSS class applied to the element, or a function that returns a class based on the component's state.	`string \| ((state: State) => string \| undefined)`
`style`Style applied to the element, or a function that returns a style object based on the component's state.	`React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined)`
`render`Allows you to replace the component's HTML element with a different tag, or compose it with another component.	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, State>`

Keyboard and accessibility

Keyboard

Keyboard
Keys	Does	Part
`Tab`	In `'list'`, moves through every step's button; the arrow keys do nothing	Trigger
`Tab`	In `'tabs'`, enters the list on the current step's tab	List
`ArrowRightArrowLeft`	In `'tabs'`, moves to the next or previous tab without changing the step	List
`ArrowDownArrowUp`	In vertical `'tabs'`, moves to the next or previous tab	List
`HomeEnd`	In `'tabs'`, moves to the first or last tab	List
`EnterSpace`	In `'tabs'`, shows the focused tab's step, validating the current one first	Trigger

Accessibility

What the parts set
Part	Sets	So that
List	the native `ol`; `role="tablist"` in `'tabs'`, with `aria-orientation` when vertical	the steps are read as a numbered list, or as tabs; a development build warns without a name
Item	the native `li`; `role="presentation"` in `'tabs'`	the count of steps comes from the list
Trigger	a `button` with `aria-current="step"` on the current step in `'list'`, or `role="tab"` with `aria-selected` in `'tabs'`; `aria-disabled` while unreachable	the current step is announced, and a step that cannot be reached says so
Title	the Trigger's name, plus a visually hidden ", completed", ", error" or ", optional"	a step's state is read with its name, not only shown by its color or icon
Description	the Trigger's `aria-describedby`	the hint is read after the name
Indicator	`aria-hidden`	the number and the check are not read twice
Separator	`aria-hidden`	the line between steps is for sight
Panel	`role="group"` named by its Title, `tabindex="-1"`; a `tabpanel` in `'tabs'`; `hidden` and `inert` while not current	focus can move to the new step, and a hidden step's fields are out of reach
Root	one polite `role="status"` region after the stepper, always mounted	a change of step is announced ("Step 2 of 3: Shipping"), since readers do not announce `aria-current` moving

Focus order

In 'list' every step's button is a Tab stop, in the list's order, then the panel's fields, then Previous and Next.
In 'tabs' the list is one Tab stop on the current step's tab; the arrow keys, Home and End move between tabs, and Enter or Space shows one.
Previous and Next stay focusable at their bounds, with aria-disabled, so a reader does not lose their place.

Installation

Anatomy

Examples

Tabs

Form

Vertical

API reference

DescriptionStepper.Description

IndicatorStepper.Indicator

ItemStepper.Item

ListStepper.List

NextStepper.Next

PanelStepper.Panel

PreviousStepper.Previous

RootStepper.Root

SeparatorStepper.Separator

TitleStepper.Title

TriggerStepper.Trigger

ValueStepper.Value