Step Header

import {
  StepHeader,
  StepHeaderAction,

The StepHeader component sits at the top of a multi-step flow such as ordering a card, verifying an identity, or sending a transfer. It shows where the user is, lets them go back or leave, and states what the current step asks for. Use StepHeaderCount with StepHeaderProgress for longer flows, and StepHeaderSteps when a short flow has three or four named steps.

Installation#

pnpmnpmyarnbun
pnpm dlx shadcn@latest add @dots/step-header
Copy

Usage#

Copyimport {
  StepHeader,
  StepHeaderBack,
  StepHeaderBar,
  StepHeaderContent,
  StepHeaderCount,
  StepHeaderHeading,
  StepHeaderProgress,
} from "@/components/ui/step-header"

Copy<StepHeader>
  <StepHeaderBar>
    <StepHeaderBack onPress={goBack} />
    <StepHeaderCount step={2} total={5} />
  </StepHeaderBar>
  <StepHeaderProgress step={2} total={5} />
  <StepHeaderContent>
    <StepHeaderHeading>Where do you live?</StepHeaderHeading>
  </StepHeaderContent>
</StepHeader>

Composition#

Use the following composition to build a step header:

CopyStepHeader
├── StepHeaderBar
│   ├── StepHeaderBack or StepHeaderClose
│   ├── StepHeaderCount or StepHeaderTitle
│   └── StepHeaderAction or StepHeaderClose side="end"
├── StepHeaderProgress or StepHeaderSteps
└── StepHeaderContent
    ├── StepHeaderHeading
    └── StepHeaderDescription

Features#

• A three-column bar that keeps the counter or title centered with or without a button on each side
• Segmented progress built on the React Aria ProgressBar, read as "Step 2 of 5"
• Partial fill of the current segment through stepProgress for a step with inner screens
• Named steps for short flows, with a check on done steps and aria-current="step" on the current one
• Back and close buttons with default labels, and a text action slot for "Skip" or "Save and exit"
• A heading level you can set to fit the page outline

First step#

On the first step there is nothing to go back to, so put StepHeaderClose at the start of the bar instead of StepHeaderBack.

import {
  StepHeader,
  StepHeaderBar,

Optional step#

Pass note to StepHeaderCount to mark a step as optional and add a StepHeaderAction to skip it. Set stepProgress to fill part of the current segment when a step has its own inner screens. When you replace the counter wording through children, pass the same text as valueLabel to StepHeaderProgress.

import {
  StepHeader,
  StepHeaderAction,

Named steps#

For a short flow of up to four steps, show the step names with StepHeaderSteps and the flow name with StepHeaderTitle. Use side="end" to put the close button at the end of the bar.

import {
  StepHeader,
  StepHeaderBack,

Changing steps#

Keep the button that moves forward, such as Continue, in the content below the header; StepHeaderAction is for a secondary action such as "Skip". When the step changes in place, the pressed Back or Continue button may unmount. Give StepHeaderHeading a ref and tabIndex={-1}, and focus it in an effect keyed on the step. Focus is not lost and the new step is read.

"use client"

import * as React from "react"

Copyconst headingRef = React.useRef<HTMLHeadingElement>(null)
// Set on a step change, so the first render does not take focus.
const changed = React.useRef(false)
 
React.useEffect(() => {
  if (changed.current) headingRef.current?.focus()
}, [step])
 
const go = (next: number) => {
  changed.current = true
  setStep(next)
}
 
<StepHeaderBack onPress={() => go(step - 1)} />
<StepHeaderHeading ref={headingRef} tabIndex={-1}>
  {current.heading}
</StepHeaderHeading>

Accessibility#

StepHeaderProgress renders a React Aria ProgressBar with role="progressbar", its value, and a value text of "Step 2 of 5". The segments are hidden from assistive tech. StepHeaderBack, StepHeaderClose, and StepHeaderAction render a Button, so they work with mouse, touch, and keyboard.

Labels#

StepHeaderBack and StepHeaderClose are icon-only and default to aria-label="Back" and aria-label="Close". Pass your own aria-label when the app is translated or the close button means something more specific, such as "Cancel transfer". StepHeaderProgress defaults to aria-label="Progress" and StepHeaderSteps to aria-label="Steps".

Named steps#

StepHeaderSteps renders an ordered list. Done steps get a visually hidden "Done:" prefix and the current step gets aria-current="step", so the state is not conveyed by the check or the color alone.

Focus on step change#

Move focus to StepHeaderHeading after each step change, as shown in Changing steps. Do not focus it on the first render.

API Reference#

StepHeader#

The root container. Make it sticky from the outside if the bar should stay visible while the content scrolls.

StepHeaderBar#

The top row with three columns. The side columns never squeeze their buttons; the center truncates on narrow screens.

StepHeaderBack#

Goes back one step. Renders an icon-only ghost Button.

StepHeaderClose#

Leaves the flow. Renders an icon-only ghost Button.

StepHeaderAction#

A text action at the end of the bar, such as "Skip" or "Save and exit". Renders a Button and accepts all of its props.

StepHeaderCount#

The "Step 2 of 5" counter in the center of the bar.

StepHeaderTitle#

The flow name in the center of the bar, used with named steps.

StepHeaderProgress#

Segmented progress built on the React Aria ProgressBar. Passed and current segments are filled, the rest show the track.

StepHeaderSteps#

Named steps for short flows, rendered as an ordered list.

StepHeaderContent#

Wraps the step heading and description under the progress.

StepHeaderHeading#

The question or task of the step, such as "Where do you live?".

StepHeaderDescription#

A short line under the heading that explains why the step is needed.