ui/components/stepper

Stepper

Step-by-step progress indicator with expandable steps, substeps, and five visual variants. Compound component with context-based state management, roving tabIndex keyboard model, and a polite live region for active-step announcements.

Preview

tsx

1 import { Stepper } from "@/components/ui/stepper";2 3 export default function StepperDefault() {4   return (5     <Stepper>6       <Stepper.Step stepId="select" status="completed">7         <Stepper.Trigger>Select files for review</Stepper.Trigger>8       </Stepper.Step>9       <Stepper.Step stepId="analyze" status="active">10         <Stepper.Trigger>Analyze code changes</Stepper.Trigger>11       </Stepper.Step>12       <Stepper.Step stepId="report" status="pending">13         <Stepper.Trigger>Generate review report</Stepper.Trigger>14       </Stepper.Step>15     </Stepper>16   );17 }18

Installation

$pnpm exec dgadd add ui/stepper

[Installs to]src/components/ui/stepper[Item]ui/stepper

dgadd is not public on npm yet. Until the first release, pack @diffgazer/add from the repository and install that tarball into this app, which is what puts dgadd on pnpm exec.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS once packages are available.

Usage

tsx

1 import { Stepper } from "@/components/ui/stepper";2 3 export default function StepperDefault() {4   return (5     <Stepper>6       <Stepper.Step stepId="select" status="completed">7         <Stepper.Trigger>Select files for review</Stepper.Trigger>8       </Stepper.Step>9       <Stepper.Step stepId="analyze" status="active">10         <Stepper.Trigger>Analyze code changes</Stepper.Trigger>11       </Stepper.Step>12       <Stepper.Step stepId="report" status="pending">13         <Stepper.Trigger>Generate review report</Stepper.Trigger>14       </Stepper.Step>15     </Stepper>16   );17 }18

Vertical variants

Five visual variants share the same compound API and render the same six canonical states (pending · active · completed · error · skipped · disabled). Switch with variant on the root <Stepper>.

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { Stepper, type StepperVariant } from "@/components/ui/stepper";5 import { createToggleGroup } from "@/components/ui/toggle-group";6 7 const VARIANTS = [8   "ascii",9   "numbered",10   "bullet",11   "tag",12   "progress",13 ] as const satisfies readonly StepperVariant[];14 15 const StepperVariantGroup = createToggleGroup(VARIANTS);16 17 export default function StepperVariants() {18   const [variant, setVariant] = useState<StepperVariant>("ascii");19 20   return (21     <div className="flex flex-col gap-4">22       <StepperVariantGroup23         value={variant}24         onChange={(v) => v && setVariant(v)}25         label="Stepper variant"26       >27         {VARIANTS.map((value) => (28           <StepperVariantGroup.Item key={value} value={value}>29             {value}30           </StepperVariantGroup.Item>31         ))}32       </StepperVariantGroup>33 34       <Stepper variant={variant}>35         <Stepper.Step stepId="init" status="completed">36           <Stepper.Trigger>Init repository</Stepper.Trigger>37         </Stepper.Step>38         <Stepper.Step stepId="install" status="completed">39           <Stepper.Trigger>Install dependencies</Stepper.Trigger>40         </Stepper.Step>41         <Stepper.Step stepId="build" status="active">42           <Stepper.Trigger>Build production bundle</Stepper.Trigger>43         </Stepper.Step>44         <Stepper.Step stepId="test" status="error">45           <Stepper.Trigger>Run tests</Stepper.Trigger>46         </Stepper.Step>47         <Stepper.Step stepId="deploy" status="pending">48           <Stepper.Trigger>Deploy</Stepper.Trigger>49         </Stepper.Step>50         <Stepper.Step stepId="notify" status="skipped">51           <Stepper.Trigger>Notify (optional)</Stepper.Trigger>52         </Stepper.Step>53         <Stepper.Step stepId="rollback" status="disabled">54           <Stepper.Trigger>Rollback (locked)</Stepper.Trigger>55         </Stepper.Step>56       </Stepper>57     </div>58   );59 }60

ascii. Default. Mono 1ch bracket glyphs ([x] [~] [ ] [!]) with a blinking cursor on the active step. Pure terminal idiom — matches dialog brackets, code-block chrome, and CLI output.
numbered. 20px square with the CSS-counter step number; swaps to ✓ on completed. Use for form wizards and onboarding where the step number matters to the user.
bullet. Single Unicode glyph per state (• · › · · · ×) with a dashed connector. Minimal chrome — use when the stepper is one of many UI elements.
tag. Uppercase text tag (DONE · RUN · WAIT · FAIL · SKIP · OFF) with a fixed min-width so the active state never shifts neighbour widths. Use for CI / build / deploy surfaces where users read status as text.
progress. Unicode block-element bar (███ / █▌░ / ░░░) per step. Strong terminal flavor; best for short lists (3–5 steps) where granular per-step progress matters.

Six canonical states

Preview

tsx

1 import { Stepper } from "@/components/ui/stepper";2 3 export default function StepperStateMatrix() {4   return (5     <Stepper variant="ascii">6       <Stepper.Step stepId="completed" status="completed">7         <Stepper.Trigger>Completed — step finished successfully</Stepper.Trigger>8       </Stepper.Step>9       <Stepper.Step stepId="active" status="active">10         <Stepper.Trigger>Active — currently focused step</Stepper.Trigger>11       </Stepper.Step>12       <Stepper.Step stepId="pending" status="pending">13         <Stepper.Trigger>Pending — not yet reached</Stepper.Trigger>14       </Stepper.Step>15       <Stepper.Step stepId="error" status="error">16         <Stepper.Trigger>Error — validation failed</Stepper.Trigger>17       </Stepper.Step>18       <Stepper.Step stepId="skipped" status="skipped">19         <Stepper.Trigger>Skipped — optional step bypassed</Stepper.Trigger>20       </Stepper.Step>21       <Stepper.Step stepId="disabled" status="disabled">22         <Stepper.Trigger>Disabled — policy gate (not reachable)</Stepper.Trigger>23       </Stepper.Step>24     </Stepper>25   );26 }27

For compact CI bars, wizard headers, and breadcrumb-style paths, use the separate Horizontal Stepper primitive.

More examples

Auto tone

Preview

tsx

1 import { Stepper } from "@/components/ui/stepper";2 3 // Tone is derived from `status` by the built-in variant dictionary:4 //   completed → primary · active → foreground · error → error5 //   pending → muted · skipped → muted (line-through) · disabled → muted (dim)6 // No per-step color wiring required — the indicator glyph still carries7 // meaning (WCAG 1.4.1), color only reinforces it.8 export default function StepperAutoTone() {9   return (10     <Stepper variant="bullet">11       <Stepper.Step stepId="tag" status="completed">12         <Stepper.Trigger>Tag release</Stepper.Trigger>13       </Stepper.Step>14       <Stepper.Step stepId="publish" status="completed">15         <Stepper.Trigger>Publish npm</Stepper.Trigger>16       </Stepper.Step>17       <Stepper.Step stepId="docs" status="active">18         <Stepper.Trigger>Update docs</Stepper.Trigger>19       </Stepper.Step>20       <Stepper.Step stepId="cache" status="error">21         <Stepper.Trigger>Cache warm-up</Stepper.Trigger>22       </Stepper.Step>23       <Stepper.Step stepId="notify" status="pending">24         <Stepper.Trigger>Notify Slack</Stepper.Trigger>25       </Stepper.Step>26     </Stepper>27   );28 }29

With substeps

Preview

tsx

1 import { Stepper } from "@/components/ui/stepper";2 3 export default function StepperSubsteps() {4   return (5     <Stepper defaultExpandedIds={["parse", "analyze"]}>6       <Stepper.Step stepId="parse" status="completed">7         <Stepper.Trigger>Parse diff</Stepper.Trigger>8         <Stepper.Content>9           <div className="space-y-1">10             <Stepper.Substep tag="GIT" label="Read git diff" status="completed" />11             <Stepper.Substep tag="AST" label="Parse file changes" status="completed" />12           </div>13         </Stepper.Content>14       </Stepper.Step>15       <Stepper.Step stepId="analyze" status="active">16         <Stepper.Trigger>AI analysis</Stepper.Trigger>17         <Stepper.Content>18           <div className="space-y-1">19             <Stepper.Substep tag="SEC" label="Security review" status="completed" />20             <Stepper.Substep tag="BUG" label="Bug detection" status="active" />21             <Stepper.Substep tag="STY" label="Style suggestions" status="pending" />22           </div>23         </Stepper.Content>24       </Stepper.Step>25       <Stepper.Step stepId="report" status="pending">26         <Stepper.Trigger>Build report</Stepper.Trigger>27         <Stepper.Content>28           <div className="space-y-1">29             <Stepper.Substep tag="FMT" label="Format findings" status="pending" />30             <Stepper.Substep tag="OUT" label="Write output" status="pending" />31           </div>32         </Stepper.Content>33       </Stepper.Step>34     </Stepper>35   );36 }37

Controlled expansion

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { Stepper } from "@/components/ui/stepper";5 6 export default function StepperInteractive() {7   const [expandedIds, setExpandedIds] = useState<string[]>(["step-2"]);8 9   return (10     <Stepper expandedIds={expandedIds} onExpandedChange={setExpandedIds}>11       <Stepper.Step stepId="step-1" status="completed">12         <Stepper.Trigger>Environment setup</Stepper.Trigger>13         <Stepper.Content>14           <div className="text-sm text-muted-foreground">Node.js 22, pnpm 9.15</div>15         </Stepper.Content>16       </Stepper.Step>17       <Stepper.Step stepId="step-2" status="completed">18         <Stepper.Trigger>Install dependencies</Stepper.Trigger>19         <Stepper.Content>20           <div className="text-sm text-muted-foreground">Installed 847 packages in 12.3s</div>21         </Stepper.Content>22       </Stepper.Step>23       <Stepper.Step stepId="step-3" status="active">24         <Stepper.Trigger>Run tests</Stepper.Trigger>25         <Stepper.Content>26           <div className="text-sm text-foreground">Running 45 test suites...</div>27         </Stepper.Content>28       </Stepper.Step>29       <Stepper.Step stepId="step-4" status="pending">30         <Stepper.Trigger>Deploy</Stepper.Trigger>31       </Stepper.Step>32     </Stepper>33   );34 }35

Error recovery

Preview

tsx

1 import { Stepper } from "@/components/ui/stepper";2 3 export default function StepperCustom() {4   return (5     <Stepper defaultExpandedIds={["lint", "test"]}>6       <Stepper.Step stepId="lint" status="completed">7         <Stepper.Trigger>Lint check</Stepper.Trigger>8         <Stepper.Content>9           <div className="space-y-1">10             <Stepper.Substep tag="ESL" label="ESLint" status="completed" detail="0 errors" />11             <Stepper.Substep tag="TSC" label="TypeScript" status="completed" detail="0 errors" />12           </div>13         </Stepper.Content>14       </Stepper.Step>15       <Stepper.Step stepId="test" status="active">16         <Stepper.Trigger>Test suite</Stepper.Trigger>17         <Stepper.Content>18           <div className="space-y-1">19             <Stepper.Substep tag="UT" label="Unit tests" status="completed" />20             <Stepper.Substep21               tag="IT"22               label="Integration tests"23               status="error"24               detail="2 failures"25             />26             <Stepper.Substep tag="E2E" label="E2E tests" status="pending" />27           </div>28         </Stepper.Content>29       </Stepper.Step>30       <Stepper.Step stepId="build" status="pending">31         <Stepper.Trigger>Build artifacts</Stepper.Trigger>32       </Stepper.Step>33     </Stepper>34   );35 }36

Preview

tsx

1 "use client";2 3 import { useRef, useState } from "react";4 import { Stepper } from "@/components/ui/stepper";5 // @hidden-imports-ok — demo imports the useNavigation re-export from the hidden use-navigation hook registry item6 import { useNavigation } from "@/hooks/use-navigation";7 8 const steps = [9   {10     id: "checkout",11     label: "Checkout repository",12     status: "completed" as const,13     detail: "Cloned main branch at commit a3f8c21.",14   },15   {16     id: "build",17     label: "Build project",18     status: "completed" as const,19     detail: "Compiled 128 modules in 4.7s.",20   },21   {22     id: "test",23     label: "Run test suite",24     status: "active" as const,25     detail: "Executing 87 tests across 12 suites...",26   },27   { id: "deploy", label: "Deploy to staging", status: "pending" as const },28 ];29 30 export default function StepperKeyboard() {31   const containerRef = useRef<HTMLOListElement>(null);32   const [expandedIds, setExpandedIds] = useState<string[]>(["build"]);33 34   const { onKeyDown } = useNavigation({35     containerRef,36     role: "button",37     wrap: true,38     moveFocus: true,39     onSelect: (id) =>40       setExpandedIds((prev) => (prev.includes(id) ? prev.filter((v) => v !== id) : [...prev, id])),41   });42 43   return (44     <div className="flex flex-col gap-2">45       <Stepper46         ref={containerRef}47         expandedIds={expandedIds}48         onExpandedChange={setExpandedIds}49         onKeyDown={onKeyDown}50       >51         {steps.map((step) => (52           <Stepper.Step key={step.id} stepId={step.id} status={step.status}>53             <Stepper.Trigger role="button" data-value={step.id}>54               {step.label}55             </Stepper.Trigger>56             {step.detail && (57               <Stepper.Content>58                 <div59                   className={`text-sm ${step.status === "active" ? "text-foreground" : "text-muted-foreground"}`}60                 >61                   {step.detail}62                 </div>63               </Stepper.Content>64             )}65           </Stepper.Step>66         ))}67       </Stepper>68       <p className="text-xs text-muted-foreground">69         Tab into the list, then ↑↓ to navigate steps · Enter/Space toggles. The focused step draws70         the outside focus ring (2px, --ring, offset 2px) around its whole row.71       </p>72     </div>73   );74 }75

API Reference

Stepper

Name	Type	Default	Description
variant	"ascii" \| "numbered" \| "bullet" \| "tag" \| "progress"	"ascii"	Visual variant. Controls the indicator glyph and connector treatment across every step.
expandedIds	string[]	—	Controlled set of currently expanded step ids.
defaultExpandedIds	string[]	—	Initial expanded ids for uncontrolled mode.
onExpandedChange	(ids: string[]) => void	—	Fired when the expanded set changes.
childrenrequired	ReactNode	—	StepperStep children rendered inside an <ol>.

StepperStep

Name	Type	Default	Description
stepIdrequired	string	—	Stable identifier matched against expandedIds.
statusrequired	"pending" \| "active" \| "completed" \| "error" \| "skipped" \| "disabled"	—	Step status. Drives the indicator glyph, label styling, aria-current, aria-disabled, and tab-order eligibility.
childrenrequired	ReactNode	—	StepperTrigger and optional StepperContent.

StepperTrigger

Name	Type	Default	Description
statusLabels	Partial<Record<"pending" \| "active" \| "completed" \| "error" \| "skipped" \| "disabled", string>>	{ completed: "DONE", active: "RUN", pending: "WAIT", error: "FAIL", skipped: "SKIP", disabled: "OFF" }	Per-status indicator label overrides. Used directly by `variant="tag"`; other variants use these labels as the screen-reader fallback for the indicator glyph.
indicatorClassName	string	—	Classes merged onto the indicator span, for repainting it from an app-owned palette.
labelClassName	string	—	Classes merged onto the label span. Same seam as indicatorClassName.
childrenrequired	ReactNode	—	Step label rendered next to the indicator glyph.

StepperContent

Name	Type	Default	Description
childrenrequired	ReactNode	—	Expandable content (e.g. nested StepperSubstep rows). aria-hidden and inert when collapsed.
region	boolean	false	Opt in to role="region" with aria-labelledby pointing at the trigger while the step is expanded. Off by default, matching AccordionContent and the APG disclosure pattern: a Stepper can hold any number of simultaneously expanded steps, and one landmark per step is rotor noise. Enable it for a small number of substantive panels.

StepperSubstep

Name	Type	Default	Description
tagrequired	string	—	Short tag (e.g. step number or code) rendered inside a status-colored Badge.
labelrequired	string	—	Accessible label text for the substep.
statusrequired	"pending" \| "active" \| "completed" \| "error"	—	Current substep status. Substeps keep the original four-state lifecycle (skipped/disabled apply only to top-level steps).
detail	string	—	Trailing detail text. Overrides the status label fallback.
statusLabels	Partial<Record<"pending" \| "active" \| "completed" \| "error", string>>	—	Per-status fallback labels shown when detail is omitted.

Data attributes

Attribute	Applies to	Values	Description
data-state	StepperStep	"open" \| "closed"	Expanded/collapsed state for the step content.
data-status	StepperStep / StepperTrigger	"pending" \| "active" \| "completed" \| "error" \| "skipped" \| "disabled"	Canonical step lifecycle state used by indicators and labels.
data-step-id	StepperTrigger	step id	Stable id used by roving focus, expansion lookup, and trigger/content linking.
data-variant	Stepper	"ascii" \| "numbered" \| "bullet" \| "tag" \| "progress"	Visual indicator and connector variant.
data-counter	StepperTrigger	present in numbered variant	CSS-counter hook for numbered indicators.

Accessibility

Keyboard Navigation

Roving tabIndex: a single Tab key reaches the stepper. Arrow keys (Up/Down/Left/Right) move focus between enabled steps and skip disabled ones. Home/End jump to the first/last enabled step. Enter or Space toggles direct StepperContent.

Key	Action
ArrowUp / ArrowLeft	Moves focus to the previous enabled StepperTrigger.
ArrowDown / ArrowRight	Moves focus to the next enabled StepperTrigger.
Home / End	Moves focus to the first or last enabled trigger.
Enter / Space	Toggles the focused step content when present.

Controlled expansion with keyboard

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { Stepper } from "@/components/ui/stepper";5 6 export default function StepperInteractive() {7   const [expandedIds, setExpandedIds] = useState<string[]>(["step-2"]);8 9   return (10     <Stepper expandedIds={expandedIds} onExpandedChange={setExpandedIds}>11       <Stepper.Step stepId="step-1" status="completed">12         <Stepper.Trigger>Environment setup</Stepper.Trigger>13         <Stepper.Content>14           <div className="text-sm text-muted-foreground">Node.js 22, pnpm 9.15</div>15         </Stepper.Content>16       </Stepper.Step>17       <Stepper.Step stepId="step-2" status="completed">18         <Stepper.Trigger>Install dependencies</Stepper.Trigger>19         <Stepper.Content>20           <div className="text-sm text-muted-foreground">Installed 847 packages in 12.3s</div>21         </Stepper.Content>22       </Stepper.Step>23       <Stepper.Step stepId="step-3" status="active">24         <Stepper.Trigger>Run tests</Stepper.Trigger>25         <Stepper.Content>26           <div className="text-sm text-foreground">Running 45 test suites...</div>27         </Stepper.Content>28       </Stepper.Step>29       <Stepper.Step stepId="step-4" status="pending">30         <Stepper.Trigger>Deploy</Stepper.Trigger>31       </Stepper.Step>32     </Stepper>33   );34 }35

Keyboard navigation

Preview

tsx

1 "use client";2 3 import { useRef, useState } from "react";4 import { Stepper } from "@/components/ui/stepper";5 // @hidden-imports-ok — demo imports the useNavigation re-export from the hidden use-navigation hook registry item6 import { useNavigation } from "@/hooks/use-navigation";7 8 const steps = [9   {10     id: "checkout",11     label: "Checkout repository",12     status: "completed" as const,13     detail: "Cloned main branch at commit a3f8c21.",14   },15   {16     id: "build",17     label: "Build project",18     status: "completed" as const,19     detail: "Compiled 128 modules in 4.7s.",20   },21   {22     id: "test",23     label: "Run test suite",24     status: "active" as const,25     detail: "Executing 87 tests across 12 suites...",26   },27   { id: "deploy", label: "Deploy to staging", status: "pending" as const },28 ];29 30 export default function StepperKeyboard() {31   const containerRef = useRef<HTMLOListElement>(null);32   const [expandedIds, setExpandedIds] = useState<string[]>(["build"]);33 34   const { onKeyDown } = useNavigation({35     containerRef,36     role: "button",37     wrap: true,38     moveFocus: true,39     onSelect: (id) =>40       setExpandedIds((prev) => (prev.includes(id) ? prev.filter((v) => v !== id) : [...prev, id])),41   });42 43   return (44     <div className="flex flex-col gap-2">45       <Stepper46         ref={containerRef}47         expandedIds={expandedIds}48         onExpandedChange={setExpandedIds}49         onKeyDown={onKeyDown}50       >51         {steps.map((step) => (52           <Stepper.Step key={step.id} stepId={step.id} status={step.status}>53             <Stepper.Trigger role="button" data-value={step.id}>54               {step.label}55             </Stepper.Trigger>56             {step.detail && (57               <Stepper.Content>58                 <div59                   className={`text-sm ${step.status === "active" ? "text-foreground" : "text-muted-foreground"}`}60                 >61                   {step.detail}62                 </div>63               </Stepper.Content>64             )}65           </Stepper.Step>66         ))}67       </Stepper>68       <p className="text-xs text-muted-foreground">69         Tab into the list, then ↑↓ to navigate steps · Enter/Space toggles. The focused step draws70         the outside focus ring (2px, --ring, offset 2px) around its whole row.71       </p>72     </div>73   );74 }75

Notes

Visual variants (vertical)

Five variants: ascii (default — mono 1ch bracket glyphs with blinking active cursor), numbered (CSS-counter square with ✓ on completed), bullet (single glyph with dashed connector), tag (uppercase text tag, no width shift on active), progress (Unicode block-element bar per step). All variants render the same six canonical states.

Six canonical states

pending · active · completed · error · skipped · disabled. `skipped` ≠ `completed` (data integrity for form wizards). `disabled` ≠ `pending` (policy gate vs ordering). Skipped renders line-through. Disabled is non-interactive and skipped by arrow-key navigation.

State color

Completed indicators, labels, and connectors read the primary token, not success: finishing a step is neutral progress, so it stays monochrome in both themes. The status palette stays reserved for meaning — error is the only status that keeps a semantic hue.

Repainting from an app palette

An app that owns its own status palette (e.g. live-run telemetry colors) passes `indicatorClassName`/`labelClassName` on StepperTrigger instead of targeting the trigger's inner spans with descendant selectors. Both merge over the variant classes, so a single utility wins the conflict without copying the rest of the state styling.

Substep nesting

StepperContent stacks below its trigger and indents its children. Substeps draw a terminal branch rail from that indent (├─ per row, └─ on the last), so nested rows read as children of the step rather than a second column.

Keyboard model

Single roving tab stop on the active step (falls back to the first non-disabled step). Arrow keys (Up/Down/Left/Right) cycle focus and skip disabled steps. Home/End jump to first/last enabled step. Editable targets inside step content keep their native handling. The focused trigger shows the library's outside focus ring (2px --ring, 2px offset) around the whole row.

Expansion modes

Supports controlled (expandedIds + onExpandedChange) and uncontrolled (defaultExpandedIds) expansion. Multiple steps can be expanded simultaneously.

Composition contract

Keep StepperTrigger and StepperContent as explicit children of StepperStep. StepperStep only links aria-controls when it can see a direct StepperContent child; opaque wrappers that create content internally are not part of the current public contract.

Live region

Active-step transitions are announced via a persistent polite live region: 'Step {n} of {total}: {label}'. Label is sourced from the trigger's text content.

Source

Install via CLI: pnpm exec dgadd add ui/stepper. Keyboard hooks are included as standalone copies. For the full experience, use --integration keys.

Highlighted source loads after this disclosure opens. Browse the source repository.

Stepper

Installation

Usage

Vertical variants

Six canonical states

More examples

Auto tone

With substeps

Controlled expansion

Error recovery

Keyboard navigation

API Reference

Stepper

StepperStep

StepperTrigger

StepperContent

StepperSubstep

Data attributes

Accessibility

Keyboard Navigation

Controlled expansion with keyboard

Keyboard navigation

Notes

Visual variants (vertical)

Six canonical states

State color

Repainting from an app palette

Substep nesting

Keyboard model

Expansion modes

Composition contract

Live region

Source

View component source (28 files)