Stepper

A read-only display of progress through a multi-step flow.

import { Stepper } from "@merid/react";

export function Example() {
  return (
    <Stepper.Root current={1} aria-label="Checkout progress">
      <Stepper.Step title="Account" />
      <Stepper.Step title="Shipping" />
      <Stepper.Step title="Payment" />
      <Stepper.Step title="Review" />
    </Stepper.Root>
  );
}

Import

import { Stepper } from "@merid/react";

Anatomy

<Stepper.Root current={0}>
  <Stepper.Step title="…" description="…" />
</Stepper.Root>

• Stepper.Root — an ordered list. current is the zero-based index of the active step; earlier steps are complete, later ones upcoming.
• Stepper.Step — one step with a numbered marker (a check when complete), a title and an optional description.

Examples

Vertical with descriptions

<Stepper.Root current={2} orientation="vertical" aria-label="Onboarding">
  <Stepper.Step title="Create workspace" description="Name and region" />
  <Stepper.Step title="Invite team" description="Add up to 10 people" />
  <Stepper.Step title="Connect data" description="Import from CSV or an API" />
  <Stepper.Step title="Go live" />
</Stepper.Root>

Responsive behaviour

In horizontal orientation, titles and descriptions stay on one line and truncate with an ellipsis; string titles keep the full text in a title attribute. The stepper measures its own width (a CSS container query, not the viewport): below 560px it switches to a compact layout where only the current step shows its title and the others collapse to their numbered or checked markers. Collapsed titles stay in the accessibility tree, so screen readers hear every step either way, and narrow columns need no JavaScript or orientation switch.

API reference

Stepper.Root

Renders <ol> and accepts all its HTML attributes.

Stepper.Step

Renders <li> and accepts its HTML attributes except title. Must be a direct child of Stepper.Root.

Styling

• .mrd-stepper[data-orientation] — root list, horizontal or vertical.
• .mrd-stepper__step[data-state] — complete, current or upcoming.
• .mrd-stepper__marker — 28px circle: --mrd-tray when upcoming, a 1.5px --mrd-accent ring when current, --mrd-accent-soft when complete.
• .mrd-stepper__title / .mrd-stepper__description — text; the title turns --mrd-ink on the current step.
• .mrd-stepper__step::after — the 1px --mrd-line connector between steps.

Accessibility

There is no APG pattern for steppers. It is a static ordered list — the same structure the APG landmark and list guidance recommends for structured content — and it is not interactive.

• The list is named "Progress" by default; set aria-label to describe the flow.
• The current step has aria-current="step".
• Each step ends with a visually hidden status word ("Completed", "Current step", "Not started"), overridable with statusLabels for localisation.
• Markers are aria-hidden; the number is conveyed by list position.

Steps are not focusable, so there are no keyboard interactions. If people can jump back to a step, put links or buttons inside the step content.

Guidelines

Related

• Progress
• Tabs
• Pagination