caliper uidocs
DemoSign inGet Pro

Stepper

Free

Shows where someone is in a multi-step flow and lets them go back.

Installs components/ui/stepper.tsxDepends on lucide-reactMotion shared motion tokens
pnpm dlx shadcn@latest add https://caliperui.site/r/stepper.json

When to use #

Use it for

  • Onboarding, checkout and set-up flows with two to six steps.
  • A step can fail and needs an inline error.

Skip it when

  • The steps are not sequential; use tabs.
  • The flow is a single form; use sections.

Installation #

terminal
pnpm dlx shadcn@latest add https://caliperui.site/r/stepper.json

Adds its 2 files to components/ui/, each with its own stylesheet, and installs their packages. No account needed. The first part also adds Caliper UI’s tokens; import them once as in Installation.

Usage #

This is the code behind the preview above.

example.tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { Stepper } from "@/components/ui/stepper"

export function OnboardingSteps() {
  const steps = [
    { id: "account", label: "Account", description: "Name and email" },
    { id: "workspace", label: "Workspace", description: "Where the work lives" },
    { id: "plan", label: "Plan" },
  ];
  const [step, setStep] = useState(1);
  return (
    <div className="grid w-full max-w-xl gap-4">
      <Stepper steps={steps} current={step} onStepSelect={setStep} />
      <div className="flex gap-2">
        <Button size="sm" variant="secondary" onClick={() => setStep((value) => Math.max(0, value - 1))}>Back</Button>
        <Button size="sm" onClick={() => setStep((value) => Math.min(steps.length, value + 1))}>Continue</Button>
      </div>
    </div>
  );
}

API reference #

Stepper

component
PropTypeDefault
steps *readonly Step[]—
current *number—
orientation"horizontal" | "vertical""horizontal"
onStepSelect((index: number) => void)—
labelstring"Progress"
completeLabelstring"All steps complete"
classNamestring—

Accessibility #

It is built on native elements and keeps aria-label, aria-live, aria-hidden, aria-current and aria-disabled in step with state. Changes that matter are announced through a live region.

KeyBehaviour
→Moves to the next item or value.
↓Moves to the next item or value.
←Moves to the previous item or value.
↑Moves to the previous item or value.
HomeJumps to the first item or the minimum.
EndJumps to the last item or the maximum.

Motion #

Transitions use the shared duration and easing tokens. Under prefers-reduced-motion those tokens collapse to instant and travel distances go to zero, so state changes still happen without movement.