Skip to content

Design system

Documentation

DesignComponents / Steps

Components / Steps

Beta

Steps

Show where someone is in a multi-stage task without taking ownership of the task itself.

On this page

Examples

Current and completed steps

Current progress is derived from the feature's active step index.

  1. Account

    Add a workspace owner.

    Complete
  2. Workspace

    Choose a name and region.

    Current step
  3. Review

    Confirm the setup details.

    Not started

Workspace setup steps

Error and unavailable steps

Use explicit statuses when a step needs attention or cannot be reached yet.

  1. Choose file

    Select a CSV file.

    Complete
  2. Map columns

    Two columns need attention.

    Needs attention
  3. Import

    Continue when mapping is complete.

    Unavailable

Import steps with error and disabled statuses

Try the progress

Compare the current index and orientation with the same three-step fixture.

  1. Account

    Owner and sign-in details.

    Complete
  2. Workspace

    Name and default region.

    Current step
  3. Review

    Confirm before finishing.

    Not started

Steps property playground

When to use

Use Steps to orient people in a task with a meaningful order and a known next stage. Use Tabs for peer views that can be revisited independently. Steps is presentational; the surrounding feature decides when a stage is valid or complete.

Usage

import { Steps, type StepItem } from "@phuctech/ui/components/steps";

const steps: StepItem[] = [
{ title: "Account" },
{ title: "Workspace" },
{ title: "Review" },
];

<Steps aria-label="Workspace setup" items={steps} currentStep={1} />

The zero-based currentStep derives earlier items as complete, the matching item as current, and later items as waiting. Each item may provide an explicit status to show an error or unavailable stage. A horizontal list stacks its items vertically below the 640px small breakpoint to keep step content inside narrow viewports; on larger screens it remains horizontal and can scroll when its items exceed the available width.

States

  • finish marks a completed stage.
  • process marks the current stage and exposes aria-current="step".
  • wait marks a future stage.
  • error and disabled are explicit item statuses; include visible explanatory text in the item description or nearby feature content.

API

Component API
PropTypeDefaultDescriptionConstraints
itemsreadonly StepItem[]requiredOrdered titles with optional descriptions and status overrides.Use short labels and keep the workflow sequence stable.
currentStepnumberrequiredZero-based current item index.A current index outside the item range leaves no item with aria-current.
orientation"horizontal" | "vertical""horizontal"Preferred arrangement of the step list.Horizontal steps stack vertically below 640px and can scroll horizontally on larger viewports when they exceed the available width.
StepItem.status"wait" | "process" | "finish" | "error" | "disabled"derived from currentStepExplicit display state for an item.Use error/disabled only when the feature state calls for it.
ol propsnative ordered-list props—Forwards className, ref, aria-label, and other list attributes.Give the list a concise accessible name.

Tokens

Component tokens
TokenRoleEffective valueUsage
--color-success-* / --color-danger-*Completed and error statesSemantic status rolesKeeps status meaning consistent in light and dark themes.
--color-action-primary / --color-border-strongCurrent and waiting statesSemantic rolesSeparates the active step from upcoming work.
--size-control-mdStep marker2remKeeps the numbered markers aligned with the shared control scale.

Accessibility

Steps renders an ordered list. The active index has aria-current="step"; each state also has a visually hidden text label, so meaning does not depend on color or the marker alone. Supply a list name with aria-label.

Do and don’t

Do

Keep status and completion connected to the actual feature flow.

Don’t

Use Steps as navigation when stages are independent pages or tabs.

  • Tabs switches among peer views.
  • Alert explains a blocking step error.
  • Progress summarizes continuous work as a single measure.