ui/components/horizontal-stepper

Horizontal Stepper

Compact horizontal progress stepper for CI bars, wizard headers, and breadcrumb-style progress. It is display-only: the active value derives completed, active, and pending step states.

Preview

tsx

1 import { HorizontalStepper } from "@/components/ui/horizontal-stepper";2 3 export default function HorizontalStepperDefault() {4   return (5     <HorizontalStepper value="review">6       <HorizontalStepper.Step value="select">SELECT</HorizontalStepper.Step>7       <HorizontalStepper.Step value="review">REVIEW</HorizontalStepper.Step>8       <HorizontalStepper.Step value="confirm">CONFIRM</HorizontalStepper.Step>9       <HorizontalStepper.Step value="done">DONE</HorizontalStepper.Step>10     </HorizontalStepper>11   );12 }13

Installation

$pnpm exec dgadd add ui/horizontal-stepper

[Installs to]src/components/ui/horizontal-stepper[Item]ui/horizontal-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 { HorizontalStepper } from "@/components/ui/horizontal-stepper";2 3 export default function HorizontalStepperDefault() {4   return (5     <HorizontalStepper value="review">6       <HorizontalStepper.Step value="select">SELECT</HorizontalStepper.Step>7       <HorizontalStepper.Step value="review">REVIEW</HorizontalStepper.Step>8       <HorizontalStepper.Step value="confirm">CONFIRM</HorizontalStepper.Step>9       <HorizontalStepper.Step value="done">DONE</HorizontalStepper.Step>10     </HorizontalStepper>11   );12 }13

Examples

Variants

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import {5   HorizontalStepper,6   type HorizontalStepperVariant,7 } from "@/components/ui/horizontal-stepper";8 import { createToggleGroup } from "@/components/ui/toggle-group";9 10 const VARIANTS = [11   { value: "ascii", label: "ascii" },12   { value: "numbered", label: "numbered" },13   { value: "breadcrumb", label: "breadcrumb" },14 ] as const satisfies readonly { value: HorizontalStepperVariant; label: string }[];15 16 const HorizontalStepperVariantGroup = createToggleGroup([17   "ascii",18   "numbered",19   "breadcrumb",20 ] as const);21 22 export default function HorizontalStepperVariants() {23   const [variant, setVariant] = useState<HorizontalStepperVariant>("ascii");24 25   return (26     <div className="flex flex-col gap-4">27       <HorizontalStepperVariantGroup28         value={variant}29         onChange={(v) => v && setVariant(v)}30         label="Horizontal stepper variant"31       >32         {VARIANTS.map(({ value, label }) => (33           <HorizontalStepperVariantGroup.Item key={value} value={value}>34             {label}35           </HorizontalStepperVariantGroup.Item>36         ))}37       </HorizontalStepperVariantGroup>38 39       <HorizontalStepper value="test" variant={variant}>40         <HorizontalStepper.Step value="init">Init</HorizontalStepper.Step>41         <HorizontalStepper.Step value="build">Build</HorizontalStepper.Step>42         <HorizontalStepper.Step value="test">Test</HorizontalStepper.Step>43         <HorizontalStepper.Step value="deploy">Deploy</HorizontalStepper.Step>44         <HorizontalStepper.Step value="verify">Verify</HorizontalStepper.Step>45       </HorizontalStepper>46     </div>47   );48 }49

Variant: ASCII (start, mid-run, done)

Preview

tsx

1 import { HorizontalStepper } from "@/components/ui/horizontal-stepper";2 3 function Pipeline({ value }: { value: string }) {4   return (5     <HorizontalStepper value={value} variant="ascii" aria-label="Release pipeline">6       <HorizontalStepper.Step value="clone">Clone</HorizontalStepper.Step>7       <HorizontalStepper.Step value="install">Install</HorizontalStepper.Step>8       <HorizontalStepper.Step value="build">Build</HorizontalStepper.Step>9       <HorizontalStepper.Step value="publish">Publish</HorizontalStepper.Step>10     </HorizontalStepper>11   );12 }13 14 export default function HorizontalStepperVariantAscii() {15   return (16     <div className="flex flex-col gap-6">17       <div className="space-y-2">18         <p className="text-2xs uppercase tracking-[0.08em] text-muted-foreground">19           First step active — nothing completed yet20         </p>21         <Pipeline value="clone" />22       </div>23       <div className="space-y-2">24         <p className="text-2xs uppercase tracking-[0.08em] text-muted-foreground">25           Mid-run — completed connectors fill behind the active step26         </p>27         <Pipeline value="build" />28       </div>29       <div className="space-y-2">30         <p className="text-2xs uppercase tracking-[0.08em] text-muted-foreground">31           Last step active — every earlier step completed32         </p>33         <Pipeline value="publish" />34       </div>35     </div>36   );37 }38

Compact / Constrained Width

Preview

tsx

1 import type { ReactNode } from "react";2 import { HorizontalStepper } from "@/components/ui/horizontal-stepper";3 4 const SETUP_STEPS = [5   { value: "storage", label: "Storage" },6   { value: "provider", label: "Provider" },7   { value: "apikey", label: "API Key" },8   { value: "model", label: "Model" },9   { value: "analysis", label: "Analysis" },10   { value: "execution", label: "Execution" },11 ];12 13 function SetupStepper({ compact }: { compact?: boolean }) {14   return (15     <HorizontalStepper value="apikey" compact={compact} aria-label="Setup progress">16       {SETUP_STEPS.map(({ value, label }) => (17         <HorizontalStepper.Step key={value} value={value}>18           {label}19         </HorizontalStepper.Step>20       ))}21     </HorizontalStepper>22   );23 }24 25 function Demo({ caption, children }: { caption: string; children: ReactNode }) {26   return (27     <div className="flex flex-col gap-2">28       <p className="text-2xs uppercase tracking-[0.08em] text-muted-foreground">{caption}</p>29       {children}30     </div>31   );32 }33 34 export default function HorizontalStepperCompact() {35   return (36     <div className="flex w-full flex-col gap-6">37       <Demo caption="Wide container — full stepper">38         <div className="border border-border p-3">39           <SetupStepper />40         </div>41       </Demo>42 43       <Demo caption="Constrained to 380px — connectors and inactive labels drop out">44         <div className="max-w-[380px] border border-border p-3">45           <SetupStepper />46         </div>47       </Demo>48 49       <Demo caption="Constrained to 280px — the run windows to previous/active/next with +N counters">50         <div className="max-w-[280px] border border-border p-3">51           <SetupStepper />52         </div>53       </Demo>54 55       <Demo caption="Constrained to 200px — only the active step is left, glyph included">56         <div className="max-w-[200px] border border-border p-3">57           <SetupStepper />58         </div>59       </Demo>60 61       <Demo caption="compact — forced at any width">62         <div className="border border-border p-3">63           <SetupStepper compact />64         </div>65       </Demo>66     </div>67   );68 }69

Progress

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { Button } from "@/components/ui/button";5 import { HorizontalStepper } from "@/components/ui/horizontal-stepper";6 7 const stepValues = ["init", "scan", "analyze", "report"] as const;8 9 export default function HorizontalStepperProgress() {10   const [currentIndex, setCurrentIndex] = useState(0);11   return (12     <div className="flex flex-col gap-4 items-start">13       <HorizontalStepper value={stepValues[currentIndex] ?? stepValues[0]}>14         {stepValues.map((v) => (15           <HorizontalStepper.Step key={v} value={v}>16             {v.toUpperCase()}17           </HorizontalStepper.Step>18         ))}19       </HorizontalStepper>20       <div className="flex gap-2">21         <Button22           variant="secondary"23           size="sm"24           bracket25           onClick={() => setCurrentIndex((i) => Math.max(0, i - 1))}26           disabled={currentIndex === 0}27         >28           BACK29         </Button>30         <Button31           variant="primary"32           size="sm"33           bracket34           onClick={() => setCurrentIndex((i) => Math.min(stepValues.length - 1, i + 1))}35           disabled={currentIndex === stepValues.length - 1}36         >37           NEXT38         </Button>39       </div>40     </div>41   );42 }43

API Reference

HorizontalStepper

Name	Type	Default	Description
valuerequired	string	—	Id of the active step.
variant	"ascii" \| "numbered" \| "breadcrumb"	"ascii"	Visual variant. Drives glyphs, connectors, and label typography.
compact	boolean	false	Forces the compact treatment (connectors hidden, only the active step labelled and prefixed with "Step 3/6 ·", glyph run windowed to previous/active/next with elision counters). When false the stepper adopts each tier automatically: the compact treatment below a 36rem container, and the window at a threshold derived from the variant and the step count. Below a 14rem container only the active step remains, with or without this prop.
aria-label	string	"Progress"	Accessible name for the root ordered list.
childrenrequired	ReactNode	—	HorizontalStepper.Step children in render order. Their value props define the step ids.
className	string	—	Additional class names merged onto the root ordered list.

HorizontalStepper.Step

Name	Type	Default	Description
valuerequired	string	—	Step id matched against the parent value to derive status and order.
childrenrequired	ReactNode	—	Step label.
className	string	—	Additional class names merged onto the step item.

Data attributes

Attribute	Applies to	Values	Description
data-variant	HorizontalStepper	"ascii" \| "numbered" \| "breadcrumb"	Visual variant on the root ordered list.
data-status	HorizontalStepper.Step	"completed" \| "active" \| "pending"	Derived step status. It is also the only hook connector styling needs: the numbered variant fills the incoming segment on data-status=completed.
data-counter	HorizontalStepper.Step	present in numbered variant	CSS-counter hook for pending and active numbered indicators.

Accessibility

Keyboard Navigation

HorizontalStepper is display-only. It renders list semantics and aria-current for the active step, but it does not own keyboard handlers.

Notes

Status Derivation

Rendered HorizontalStepper.Step children define order. Steps before value are completed, the matching step is active, and following steps are pending.

Variants

ascii renders inline bracket glyphs with text connectors, numbered renders a numbered indicator on a continuous line, and breadcrumb renders slash-separated labels. Completed indicators and connectors read the primary token, so progress stays monochrome in both themes; the status palette is reserved for meaning.

Glyph Hierarchy

ascii glyphs share the form family's grammar: the brackets render muted as chrome and the inner mark ([x], [~]) keeps the step's status tone at bold weight, so completed and active marks carry the contrast and a pending [ ] reads entirely as chrome. The visible text is unchanged.

Root Element

The root accepts the full ordered-list contract: id, data-*, ref, and any other <ol> attribute is spread onto the element, matching the vertical Stepper.

Constrained Containers

Steps and connectors never break internally, so a narrow parent cannot wrap a label mid-word or split the [ ] glyph across two lines. The root declares a container query instead, in three tiers. Below 36rem of inline space the stepper collapses to the compact treatment: connectors drop out, non-active labels leave the layout, and the active label is prefixed with "Step 3/6 ·". Narrower still, the glyph run becomes a viewfinder window — previous, active, next, plus muted "+2" / "+1" counters for the steps it elides — which makes the run a constant width for any step count. That window engages from need, not from a blanket width: the threshold is keyed by variant and step count, so a four-step ascii run keeps its full run down to 18rem while a twelve-step run windows from 32rem. Below 14rem only the active step remains, but its glyph never drops: the stepper always shows progress. Because every switch is a container query and not a viewport breakpoint, the same stepper adapts inside a sidebar, a dialog, and a full-width page without the consumer branching. Pass compact to force the first two tiers at any width; the narrowest still follows the container.

Accessibility

The root is an ordered list named by aria-label (default "Progress"). The active item exposes aria-current="step", and each item includes screen-reader status text: Completed, Current, or Upcoming. Every compact tier only collapses things visually — every step and its label stay in the accessibility tree at every width. The "Step 3/6 ·" prefix and the "+2" / "+1" elision counters are aria-hidden, because list position and the step statuses already carry that information.

Source

Install via CLI: pnpm exec dgadd add ui/horizontal-stepper.

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

Horizontal Stepper

Installation

Usage

Examples

Variants

Variant: ASCII (start, mid-run, done)

Compact / Constrained Width

Progress

API Reference

HorizontalStepper

HorizontalStepper.Step

Data attributes

Accessibility

Keyboard Navigation

Notes

Status Derivation

Variants

Glyph Hierarchy

Root Element

Constrained Containers

Accessibility

Source

View component source (14 files)