Stepper

Playground

import {  Stepper, StepperList, StepperStep, StepperMarker,  StepperLabel, StepperDescription, StepperPanel,} from "@/components/ui/stepper";
<Stepper size="md" orientation="horizontal" defaultValue="account">  <StepperList label="Setup progress">    {steps.map((step, i) => (    <StepperStep value={step.value} state={step.state}>      <StepperMarker>{i + 1}</StepperMarker>      <StepperLabel>{step.title}</StepperLabel>      <StepperDescription>{step.description}</StepperDescription>    </StepperStep>    ))}  </StepperList>
  {steps.map((step) => (    <StepperPanel value={step.value}>{step.body}</StepperPanel>  ))}</Stepper>

Installation

npx primitiv add stepper

pnpm dlx primitiv add stepper

yarn dlx primitiv add stepper

bunx primitiv add stepper

import { Stepper } from "@/components/ui/stepper";

Anatomy

Seven parts over the headless Tabs. The rail is a tablist — each StepperStep is a real tab, so aria-selected, the roving tabindex and Home/End all come from Tabs, restyled as a circle. A step carries two independent state hooks: data-state (from Tabs) marks the current step, data-step-state (from StepperStep's state) marks the progress it holds in its own right — so a failed step keeps its error marker while you stand on a later one. Each StepperPanel links to the step of the same value.

<Stepper>  <StepperList>    <StepperStep>      <StepperMarker />      <StepperLabel />      <StepperDescription />    </StepperStep>  </StepperList>  <StepperPanel /></Stepper>

Props

Generated from the copied file’s props type and contract.json. Never hand-maintained.

Stepper

Extends HTMLDivElement — every native attribute of that element is accepted and forwarded.

StepperList

Extends HTMLDivElement — every native attribute of that element is accepted and forwarded.

StepperStep

Extends HTMLButtonElement — every native attribute of that element is accepted and forwarded.

StepperMarker

Extends HTMLSpanElement — every native attribute of that element is accepted and forwarded.

No props of its own.

StepperLabel

Extends HTMLSpanElement — every native attribute of that element is accepted and forwarded.

No props of its own.

StepperDescription

Extends HTMLSpanElement — every native attribute of that element is accepted and forwarded.

No props of its own.

StepperPanel

Extends HTMLDivElement — every native attribute of that element is accepted and forwarded.

Styling contract

40 CSS custom properties on .primitiv-stepper — mode-agnostic. These names are the stable surface; the values are not.

Keyboard

The rail is a tablist, so the steps share one tab stop and the arrows move between them. Activation is manual (unlike a plain Tabs): arrow keys move focus along the rail and Enter / Space commits, so browsing the steps never changes step under you and discards what is half-typed in the current panel. Disabled steps are skipped.

Data attributes

Emitted automatically by the headless primitive — style against these rather than adding your own state classes. Grouped by the part that emits them, since most are emitted by more than one.

Accessibility

• The rail is a real tablist and every step a tab, so aria-selected, the roving tabindex and Home/End all come from the headless Tabs — nothing here reimplements them. StepperList requires label or ariaLabelledBy: a tablist with no accessible name gives a screen-reader user no idea what the steps belong to.
• Activation is manual. Arrow keys move focus along the rail and Enter / Space commits, so browsing the steps with the keyboard never changes step under the user and discards what is half-typed in the current panel.
• A step the user cannot reach yet is a disabled step — already a Tabs.Trigger prop, already correct for keyboard and screen readers, so it stays discoverable while being skipped by the arrows. There is no separate linear prop.
• StepperMarker's tick and warning glyphs are aria-hidden decoration — the marker does not announce a step's complete / error state. Surface a failed step where it can be acted on: aria-invalid and error text on the fields inside its panel, which is also where a screen-reader user is when they hit the problem.
• compact keeps the steps in the DOM (only the markers and labels are hidden with display: none), so each panel's aria-labelledby still points at a real trigger. Swapping the rail out for a hand-rolled bar at narrow widths breaks that reference on exactly the viewport where it is least likely to be noticed.

Examples

Every example below reacts to the density control. Currently showing Styled mode.

import {  Stepper, StepperList, StepperStep, StepperMarker,  StepperLabel, StepperDescription, StepperPanel,} from "@/components/ui/stepper";import { Button } from "@/components/ui/button";import { useState } from "react";
const [current, setCurrent] = useState(0);const [furthest, setFurthest] = useState(0);
<Stepper  value={steps[current].value}  onValueChange={(v) => go(steps.findIndex((s) => s.value === v))}>  <StepperList label="Sign-up progress">    {steps.map((step, i) => (      <StepperStep        value={step.value}        state={i < furthest ? "complete" : "upcoming"}        disabled={i > furthest}      >        <StepperMarker>{i + 1}</StepperMarker>        <StepperLabel>{step.title}</StepperLabel>      </StepperStep>    ))}  </StepperList>
  {steps.map((step) => (    <StepperPanel value={step.value}>{step.body}</StepperPanel>  ))}</Stepper>
<Button variant="secondary" onClick={() => go(current - 1)}>Back</Button><Button onClick={() => go(current + 1)}>Continue</Button>

import {  Stepper, StepperList, StepperStep, StepperMarker,  StepperLabel, StepperDescription, StepperPanel,} from "@/components/ui/stepper";
<Stepper defaultValue="review">  <StepperList label="Checkout progress">    <StepperStep value="cart" state="complete">      <StepperMarker>1</StepperMarker>      <StepperLabel>Cart</StepperLabel>    </StepperStep>    <StepperStep value="payment" state="error">      <StepperMarker>2</StepperMarker>      <StepperLabel>Payment</StepperLabel>    </StepperStep>    <StepperStep value="review" state="upcoming">      <StepperMarker>3</StepperMarker>      <StepperLabel>Review</StepperLabel>    </StepperStep>  </StepperList>  {/* panels ... */}</Stepper>

import {  Stepper, StepperList, StepperStep, StepperMarker,  StepperLabel, StepperDescription, StepperPanel,} from "@/components/ui/stepper";
<Stepper orientation="vertical" defaultValue="account">  <StepperList label="Setup progress">    {/* steps ... */}  </StepperList>  {/* panels ... */}</Stepper>

import {  Stepper, StepperList, StepperStep, StepperMarker,  StepperLabel, StepperDescription, StepperPanel,} from "@/components/ui/stepper";import { useMediaQuery } from "@primitiv-ui/react";
const narrow = useMediaQuery("(max-width: 40rem)");
<Stepper value={step} onValueChange={setStep}>  <StepperList label="Setup progress" compact={narrow}>    {/* steps ... */}  </StepperList>
  {narrow && <p>Step {index + 1} of {steps.length} — {steps[index].title}</p>}
  {/* panels ... */}</Stepper>