Stepper

Shared Components

Reusable progress navigation for multi-step workflows.

Horizontal navigationRead-only verticalCompleted and upcoming steps

Responsive viewport — resize the window to explore. Direction and density apply only to this preview. Theme applies to the docs too.

stepper.tsx

"use client";

import { Stepper } from "@/components/ui/stepper";
import { Button } from "@dashboardpack/core/components/ui/button";
import { useState } from "react";

const steps = [
  {
    id: "workspace",
    title: "Workspace",
    description: "Choose a name and brand for your team.",
  },
  {
    id: "team",
    title: "Invite team",
    description: "Add teammates and assign roles.",
  },
  {
    id: "review",
    title: "Review",
    description: "Check your settings before launch.",
  },
];

export default function StepperExample() {
  const [index, setIndex] = useState(0);
  return (
    <div className="w-full max-w-lg space-y-6">
      <Stepper
        steps={steps}
        value={steps[index].id}
        onValueChange={(id) =>
          setIndex(steps.findIndex((step) => step.id === id))
        }
      />
      <div className="rounded-xl border p-5">
        <h3 className="font-medium">{steps[index].title}</h3>
        <p className="mt-2 text-sm text-muted-foreground">
          {steps[index].description}
        </p>
      </div>
      <div className="flex gap-2">
        <Button
          variant="outline"
          size="sm"
          disabled={index === 0}
          onClick={() => setIndex(index - 1)}
        >
          Back
        </Button>
        <Button
          size="sm"
          onClick={() => setIndex(index === steps.length - 1 ? 0 : index + 1)}
        >
          {index === steps.length - 1 ? "Start again" : "Continue"}
        </Button>
      </div>
      <Stepper
        orientation="vertical"
        label="Read-only onboarding status"
        steps={steps}
        value="team"
      />
    </div>
  );
}

Usage

Pass ordered steps with stable ids and set value to the current step id. Previous/current steps are selectable when onValueChange is provided. Future steps stay disabled unless allowFutureSteps is true. Form validation remains the parent’s responsibility.

Import

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

Shipped as editable source in src/components/ui/stepper.tsx in both apps. Copy the implementation below when moving it to another project. Copy the complete example from Source code for all imports and state. Add "use client" when using hooks or event handlers. See installation and theming for project setup.

Component source

The complete implementation is included in both apps. It uses the React, Radix, Lucide, and shared-core dependencies already installed in Apex. Keep your project’s semantic theme tokens when reusing it.

src/components/ui/stepper.tsx

import type { ReactNode } from "react";
import { Check } from "lucide-react";
import { cn } from "@dashboardpack/core/lib/utils";
export interface StepperStep {
  id: string;
  title: string;
  description?: ReactNode;
  disabled?: boolean;
}
export interface StepperProps {
  steps: StepperStep[];
  value: string;
  onValueChange?: (id: string) => void;
  allowFutureSteps?: boolean;
  orientation?: "horizontal" | "vertical";
  className?: string;
  label?: string;
}
export function Stepper({
  steps,
  value,
  onValueChange,
  allowFutureSteps = false,
  orientation = "horizontal",
  className,
  label = "Progress",
}: StepperProps) {
  const active = steps.findIndex((step) => step.id === value);
  return (
    <ol
      aria-label={label}
      className={cn(
        "flex gap-4",
        orientation === "vertical" ? "flex-col" : "flex-wrap",
        className,
      )}
    >
      {steps.map((step, index) => {
        const content = (
          <>
            <span
              aria-hidden
              className={cn(
                "flex size-8 shrink-0 items-center justify-center rounded-full border text-xs font-semibold",
                index <= active
                  ? "border-primary bg-primary text-primary-foreground"
                  : "bg-muted text-muted-foreground",
              )}
            >
              {index < active ? <Check className="size-4" /> : index + 1}
            </span>
            <span className="min-w-0 text-start">
              <span className="block text-sm font-medium">{step.title}</span>
              {step.description && (
                <span className="block text-xs text-muted-foreground">
                  {step.description}
                </span>
              )}
              {index < active && <span className="sr-only">Completed</span>}
            </span>
          </>
        );
        return (
          <li key={step.id} className="min-w-0 flex-1">
            {onValueChange ? (
              <button
                type="button"
                aria-current={index === active ? "step" : undefined}
                disabled={
                  step.disabled || (!allowFutureSteps && index > active)
                }
                onClick={() => onValueChange(step.id)}
                className="flex w-full items-center gap-3 rounded-md p-1 text-start outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-default disabled:opacity-60"
              >
                {content}
              </button>
            ) : (
              <span
                aria-current={index === active ? "step" : undefined}
                className="flex items-center gap-3 p-1"
              >
                {content}
              </span>
            )}
          </li>
        );
      })}
    </ol>
  );
}

API reference

Common props and defaults. Slot-specific props are named below; native elements also accept their standard HTML attributes. The component TypeScript definitions are the complete type reference.

Stepper props
Prop	Type / Default	Description
steps	`StepperStep[]` Default: required	Ordered ids, titles, descriptions, and optional disabled flags.
value	`string` Default: required	Current step id; must exist in steps.
onValueChange	`(id: string) => void` Default: —	Optional navigation handler.
allowFutureSteps	`boolean` Default: false	Permit selecting upcoming enabled steps.
orientation	`horizontal \| vertical` Default: horizontal	Visual layout direction.
label	`string` Default: Progress	Accessible list name.

Build with these too

Form Progress Timeline