Skip to the content

Controls and surfaces

steps

A rail that shows where one is in a sequence of steps: a row of thin segments, or numbered markers with titles, each step with a state (done, filled in for you, current, not started, skipped, blocked).

Flows and lists

When to use it

Showing progress through a known, ordered set of steps: a booking, a sign-up, an import, a checklist that runs in order. Use "segments" above a card where space is short and "labelled" where the step names help. Pair it with StepsCount ("Step 2 of 5"), which says the same in words. For a measured amount of one task use progress; for the whole guided task with its buttons use wizard, which draws this rail itself; for moving between unordered views use tabs.

See it working

The demonstration the browser checks drive, with the keyboard as well as the pointer. More of it is on the Flows and lists page.

Steps

Step 3 of 6

  1. People, Filled in for you: Two adults, from your last visit
  2. Place, Current step
  3. Extras, Skipped
  4. Payment, Blocked: Payment is not connected yet
  5. Review, Not started
  1. Match the columnsFilled in for you: Taken from the first row
  2. Check the rowsCurrent stepAbout a minute
  3. Add notesSkipped
  4. ImportNot started

Wizard

Book a table

Step 1 of 4

  1. Day, Current step
  2. People, Not started
  3. Notes, Not started
  4. Review, Not started

Step 1 of 4: Which day?

Choose a day to go on.

Step: day. Confirmed: no.

Wizard: driven from outside

Join the walk

Step 1 of 4

  1. Who, Current step
  2. Extras, Not started
  3. Pay, Not started
  4. Done, Not started

Step 1 of 4: Who is coming?

The answer is sent away, and the reply says which step comes next.

Step: who. Waiting: no. Asked:

Wizard: uncontrolled

Two questions

Step 1 of 2

  1. One, Current step
  2. Two, Not started

Step 1 of 2: The first question

Nothing outside holds the step.

Sortable list

  1. Morning market
  2. Lunch
  3. Museum
  4. Harbour walk
  5. Evening concert

Order: market, lunch, museum, walk, concert
Let go: (0). Order then:

Sortable list: whole row, uncontrolled

  1. Priority one
  2. Priority two
  3. Priority three

Combobox

Value: none

Skeleton

Add it

npx shadcn@latest add @rivier-ui/steps

The registry is named once in components.json: see Installation.

Example

Import it from @/components/ui/steps.

<StepsCount current={2} total={4} />
<Steps aria-label="Booking progress">
  <Step state="done">Dates</Step>
  <Step state="current">People</Step>
  <Step state="upcoming">Extras</Step>
  <Step state="upcoming">Review</Step>
</Steps>

// Numbered markers with titles; a finished step can be a button that goes back to it
<Steps variant="labelled" aria-label="Import">
  <Step state="done" onClick={() => goTo("file")}>Choose a file</Step>
  <Step state="assumed" note="Taken from the file's first row">Match the columns</Step>
  <Step state="current" description="About a minute">Check the rows</Step>
  <Step state="skipped">Add notes</Step>
</Steps>

What it needs

A client component: it uses state, effects or browser behaviour. Packages: lucide-react.

It imports

It is used by

Source

The whole file. Once copied it is yours: the registry item holds the same text.

src/components/ui/steps.tsx
"use client";
/**
 * @name steps
 * @category ui
 * @description A rail that shows where one is in a sequence of steps: a row of thin segments, or numbered markers with titles, each step with a state (done, filled in for you, current, not started, skipped, blocked).
 * @when Showing progress through a known, ordered set of steps: a booking, a sign-up, an import, a checklist that runs in order. Use "segments" above a card where space is short and "labelled" where the step names help. Pair it with StepsCount ("Step 2 of 5"), which says the same in words. For a measured amount of one task use progress; for the whole guided task with its buttons use wizard, which draws this rail itself; for moving between unordered views use tabs.
 * @example
 * <StepsCount current={2} total={4} />
 * <Steps aria-label="Booking progress">
 *   <Step state="done">Dates</Step>
 *   <Step state="current">People</Step>
 *   <Step state="upcoming">Extras</Step>
 *   <Step state="upcoming">Review</Step>
 * </Steps>
 *
 * // Numbered markers with titles; a finished step can be a button that goes back to it
 * <Steps variant="labelled" aria-label="Import">
 *   <Step state="done" onClick={() => goTo("file")}>Choose a file</Step>
 *   <Step state="assumed" note="Taken from the file's first row">Match the columns</Step>
 *   <Step state="current" description="About a minute">Check the rows</Step>
 *   <Step state="skipped">Add notes</Step>
 * </Steps>
 */
import { Ban, Check, Minus } from "lucide-react";
import { createContext, use, type ComponentProps, type MouseEventHandler, type ReactNode } from "react";
import { cn } from "@/lib/cn";

export type StepState = "done" | "assumed" | "current" | "upcoming" | "skipped" | "blocked";
export type StepsVariant = "segments" | "labelled";

/** The word said (and, in the labelled variant, shown where it matters) for each state. Translate them with the interface. */
export const STEP_STATE_LABELS: Record<StepState, string> = {
  done: "Done",
  assumed: "Filled in for you",
  current: "Current step",
  upcoming: "Not started",
  skipped: "Skipped",
  blocked: "Blocked",
};

const StepsContext = createContext<{ variant: StepsVariant; stateLabels: Record<StepState, string> }>({ variant: "segments", stateLabels: STEP_STATE_LABELS });

export type StepsProps = ComponentProps<"ol"> & {
  /** "segments" (default): one thin segment per step. "labelled": numbered markers with titles, in a column that becomes a row when the rail is wide enough. */
  variant?: StepsVariant;
  /** The word for each state, where the English defaults are not wanted. */
  stateLabels?: Partial<Record<StepState, string>>;
};

/**
 * An ordered list, so a screen reader says how many steps there are and which one it is on. Name it with
 * `aria-label` or `aria-labelledby`. Every step is read as its title and its state in words; the marks
 * (tick, ring, dashes, bar) repeat the state for the eye, so it never rests on colour alone.
 */
export function Steps({ className, variant = "segments", stateLabels, children, ...props }: StepsProps) {
  return (
    <div data-slot="steps" data-variant={variant} className={cn("@container w-full min-w-0", className)}>
      <ol
        data-slot="steps-list"
        className={cn("[counter-reset:rui-step]", variant === "segments" ? "flex w-full items-center gap-1.5" : "flex w-full flex-col @lg:flex-row @lg:gap-3")}
        {...props}
      >
        <StepsContext value={{ variant, stateLabels: { ...STEP_STATE_LABELS, ...stateLabels } }}>{children}</StepsContext>
      </ol>
    </div>
  );
}

export type StepProps = Omit<ComponentProps<"li">, "onClick"> & {
  state: StepState;
  /** Why the step is in this state: what was filled in and from where, or what is in the way. Read out with the state; shown under the title in the labelled variant. */
  note?: string;
  /** A line under the title in the labelled variant. */
  description?: ReactNode;
  /** Makes the step a button, for a step the person may go back to. */
  onClick?: MouseEventHandler<HTMLButtonElement>;
  /** Makes the step a link. */
  href?: string;
};

const SEGMENT: Record<StepState, string> = {
  done: "bg-primary",
  assumed: "bg-primary",
  current: "h-1.5 bg-foreground",
  upcoming: "bg-input",
  // Dashes: drawn as short pieces (see Step), so they stay dashes at any width.
  skipped: "flex h-0.5 gap-1 bg-transparent",
  blocked: "bg-destructive",
};

const MARKER: Record<StepState, string> = {
  done: "border-primary bg-primary text-primary-foreground",
  assumed: "border-primary bg-highlight-soft text-foreground",
  current: "border-2 border-foreground bg-background font-medium text-foreground",
  upcoming: "border-input bg-background text-muted-foreground",
  skipped: "border-dashed border-input bg-background text-muted-foreground",
  blocked: "border-destructive bg-background text-destructive",
};

/** The mark inside a labelled marker: an icon for the states that have one, the step's number for the rest. */
function MarkerContent({ state }: { state: StepState }) {
  if (state === "done") return <Check aria-hidden="true" strokeWidth={2} className="size-4" />;
  if (state === "skipped") return <Minus aria-hidden="true" strokeWidth={2} className="size-4" />;
  if (state === "blocked") return <Ban aria-hidden="true" strokeWidth={2} className="size-4" />;
  return <span aria-hidden="true" className="tabular-nums before:content-[counter(rui-step)]" />;
}

/**
 * One step. Its children are its title. In the segments variant the title and state are read out but not
 * shown; in the labelled variant they are shown. The current step carries `aria-current="step"`.
 */
export function Step({ className, state, note, description, onClick, href, children, ...props }: StepProps) {
  const { variant, stateLabels } = use(StepsContext);
  const stateText = `${stateLabels[state]}${note ? `: ${note}` : ""}`;
  const interactive = "rounded-control transition-opacity duration-instant ease-out hover:opacity-80 motion-reduce:transition-none";

  if (variant === "segments") {
    const body = (
      <>
        <span aria-hidden="true" data-slot="step-segment" className={cn("block h-1 w-full rounded-full", SEGMENT[state])}>
          {state === "skipped" ? Array.from({ length: 4 }, (_, piece) => <span key={piece} className="h-full flex-1 rounded-full bg-input" />) : null}
        </span>
        {state === "assumed" || state === "blocked" ? (
          // A second mark on the bar: an open ring for "filled in for you", a filled square for "blocked".
          <span
            aria-hidden="true"
            data-slot="step-mark"
            className={cn("absolute end-0 top-1/2 size-2.5 -translate-y-1/2 border-2", state === "assumed" ? "rounded-full border-primary bg-background" : "rounded-none border-destructive bg-destructive")}
          />
        ) : null}
        <span className="sr-only">
          {children}, {stateText}
        </span>
      </>
    );
    // The bar is thin; the pressable area around it is 24px tall, 40px on touch screens.
    const hit = "relative flex h-6 w-full items-center pointer-coarse:h-10";
    return (
      <li data-slot="step" data-state={state} aria-current={state === "current" ? "step" : undefined} title={note} className={cn("relative min-w-0 flex-1 [counter-increment:rui-step]", className)} {...props}>
        {href !== undefined ? (
          <a href={href} className={cn(hit, interactive)}>
            {body}
          </a>
        ) : onClick ? (
          <button type="button" onClick={onClick} className={cn(hit, interactive)}>
            {body}
          </button>
        ) : (
          <span className={hit}>{body}</span>
        )}
      </li>
    );
  }

  const body = (
    <>
      <span data-slot="step-marker" className={cn("relative z-[1] inline-flex size-7 shrink-0 items-center justify-center rounded-full border text-xs", MARKER[state])}>
        <MarkerContent state={state} />
      </span>
      <span className="flex min-w-0 flex-col gap-0.5 pt-1 text-start @lg:pt-0">
        <span data-slot="step-title" className={cn("text-sm leading-tight", state === "current" ? "font-medium text-foreground" : state === "upcoming" || state === "skipped" ? "text-muted-foreground" : "text-foreground")}>
          {children}
        </span>
        {/* The state in words. Shown where the marker alone could be misread; always read out. */}
        <span data-slot="step-state" className={cn("text-xs text-muted-foreground", state === "done" || state === "current" || state === "upcoming" ? (note ? "" : "sr-only") : "")}>
          {stateText}
        </span>
        {description ? (
          <span data-slot="step-description" className="text-xs text-muted-foreground">
            {description}
          </span>
        ) : null}
      </span>
    </>
  );
  const row = "flex w-full min-w-0 gap-3 @lg:flex-col @lg:gap-2";
  return (
    <li
      data-slot="step"
      data-state={state}
      aria-current={state === "current" ? "step" : undefined}
      className={cn(
        "relative min-w-0 pb-5 [counter-increment:rui-step] last:pb-0 @lg:flex-1 @lg:pb-0",
        // The line to the next step: down the column, or along the row.
        "before:absolute before:start-[calc(0.875rem-0.5px)] before:top-8 before:bottom-1 before:w-px before:bg-border-strong last:before:hidden",
        "@lg:before:start-9 @lg:before:end-0 @lg:before:top-[calc(0.875rem-0.5px)] @lg:before:bottom-auto @lg:before:h-px @lg:before:w-auto",
        className,
      )}
      {...props}
    >
      {href !== undefined ? (
        <a href={href} className={cn(row, interactive)}>
          {body}
        </a>
      ) : onClick ? (
        <button type="button" onClick={onClick} className={cn(row, interactive)}>
          {body}
        </button>
      ) : (
        <span className={row}>{body}</span>
      )}
    </li>
  );
}

export type StepsCountProps = ComponentProps<"p"> & {
  /** The step one is on, counted from 1. */
  current: number;
  total: number;
  /** The words. Default: "Step 2 of 5". Translate it with the interface. */
  label?: (current: number, total: number) => string;
};

/** The count in words: what the rail shows, for everyone. */
export function StepsCount({ className, current, total, label = (now, all) => `Step ${now} of ${all}`, ...props }: StepsCountProps) {
  return (
    <p data-slot="steps-count" className={cn("text-xs text-muted-foreground tabular-nums", className)} {...props}>
      {label(current, total)}
    </p>
  );
}