Progress steps

A stepper for multi-step flows with complete, current and upcoming states. It is horizontal in wide containers and switches to a vertical rail in narrow ones using container queries, or can be fixed to either orientation. The current step has aria-current="step", each step's state is spelled out for screen readers, and completed steps can be made clickable to go back.

NavigationComponentTailwind v4

Source

"use client";

import type { ReactNode } from "react";
import { Check } from "lucide-react";
import { cn } from "@/lib/utils";

export interface ProgressStep {
  id: string;
  title: ReactNode;
  description?: ReactNode;
}

export type StepState = "complete" | "current" | "upcoming";

export interface ProgressStepsProps {
  steps: ProgressStep[];
  /** Index of the current step. Steps before it are complete; use steps.length when everything is done. */
  current: number;
  /** Makes completed steps clickable, for going back to edit them. */
  onStepClick?: (index: number) => void;
  /**
   * "responsive" (default) is vertical in narrow containers and horizontal from 42rem wide, using container queries,
   * so it adapts to the space it is given rather than the window.
   */
  orientation?: "responsive" | "horizontal" | "vertical";
  label?: string;
  className?: string;
}

const stateText: Record<StepState, string> = { complete: "Completed", current: "Current step", upcoming: "Not started" };

export function ProgressSteps({ steps, current, onStepClick, orientation = "responsive", label = "Progress", className }: ProgressStepsProps) {
  // Class sets for the two layouts; "responsive" switches between them with the @2xl container query.
  const h = orientation === "horizontal";
  const r = orientation === "responsive";
  const pick = (vertical: string, horizontal: string, responsive: string) => (h ? horizontal : r ? `${vertical} ${responsive}` : vertical);

  return (
    <nav aria-label={label} className={cn("@container", className)}>
      <ol className={pick("flex flex-col", "flex flex-row", "@2xl:flex-row")}>
        {steps.map((step, index) => {
          const state: StepState = index < current ? "complete" : index === current ? "current" : "upcoming";
          const last = index === steps.length - 1;
          const clickable = state === "complete" && !!onStepClick;

          const marker = (
            <span
              data-state={state}
              className={cn(
                "relative z-10 grid size-8 shrink-0 place-items-center rounded-full border text-[13px] font-semibold tabular-nums",
                "transition-[background-color,border-color,color,box-shadow] duration-200",
                state === "complete" && "border-primary bg-primary text-primary-foreground",
                state === "current" && "border-primary bg-background text-foreground shadow-[0_0_0_4px_color-mix(in_oklab,var(--primary)_14%,transparent)]",
                state === "upcoming" && "border-border bg-background text-muted-foreground",
              )}
            >
              {state === "complete" ? <Check aria-hidden="true" className="size-4" strokeWidth={2.5} /> : index + 1}
            </span>
          );

          const text = (
            <span className="flex min-w-0 flex-col gap-0.5 text-left">
              <span className={cn("text-sm font-medium leading-5", state === "upcoming" ? "text-muted-foreground" : "text-foreground")}>
                {step.title}
              </span>
              {step.description && <span className="text-[13px] leading-5 text-muted-foreground">{step.description}</span>}
              <span className="sr-only">, {stateText[state]}</span>
            </span>
          );

          return (
            <li
              key={step.id}
              aria-current={state === "current" ? "step" : undefined}
              className={cn("relative flex min-w-0", pick("flex-row gap-4", "flex-1 flex-col gap-3", "@2xl:flex-1 @2xl:flex-col @2xl:gap-3"))}
            >
              {/* Marker plus the connector to the next step: a vertical rail, or a horizontal line. */}
              <div className={cn("flex items-center", pick("flex-col self-stretch", "flex-row", "@2xl:flex-row @2xl:self-auto"))}>
                {marker}
                {!last && (
                  <span
                    aria-hidden="true"
                    className={cn(
                      "rounded-full transition-colors duration-300",
                      pick("my-1.5 min-h-6 w-0.5 flex-1", "mx-3 h-0.5 flex-1", "@2xl:mx-3 @2xl:my-0 @2xl:h-0.5 @2xl:min-h-0 @2xl:w-auto"),
                      state === "complete" ? "bg-primary" : "bg-border",
                    )}
                  />
                )}
              </div>
              <div className={cn("min-w-0", pick(last ? "pb-0 pt-1" : "pb-7 pt-1", "pr-4", "@2xl:pb-0 @2xl:pt-0 @2xl:pr-4"))}>
                {clickable ? (
                  <button
                    type="button"
                    onClick={() => onStepClick(index)}
                    className="-m-1 flex rounded-md p-1 outline-hidden transition-colors hover:bg-accent/70 focus-visible:ring-[3px] focus-visible:ring-ring/50"
                  >
                    {text}
                  </button>
                ) : (
                  text
                )}
              </div>
            </li>
          );
        })}
      </ol>
    </nav>
  );
}