Skip to content

Progress Steps

Get Ritla UI

Shows where people are in a multi-step flow such as opening an account: a check on done steps, the brand color on the current one, gray for the rest.

Ritla scan of this preview: 41 of 41 checks3 breakpointsScanned

Open in Figma

Preview

Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.

PreviewCode
EnglishMirroredArabic
LTR →

Installation

  1. Add the component

    npx ritla add progress-steps

    Also works with shadcn: npx shadcn@latest add @ritla/progress-steps

  2. Dependencies it brings

    @phosphor-icons/react

  3. Or copy by hand

    Installing by hand copies the component's source into your project. The source comes with a Ritla UI license, so the CLI is the short way to the same files.

Usage

progress-steps.tsx
import { ProgressStep, ProgressSteps } from "@/components/ui/progress-steps";<ProgressSteps current={2} aria-label="Account opening">  <ProgressStep href="/open/details">Personal details</ProgressStep>  <ProgressStep>Verify ID</ProgressStep>  <ProgressStep>Address</ProgressStep></ProgressSteps>

Examples

Minimal

Dots on a line with the labels above, up to six steps.

EnglishMirroredArabic
LTR →

Icons

An icon in each circle; done steps still show the check.

EnglishMirroredArabic
LTR →

Vertical

For phones and side panels.

EnglishMirroredArabic
LTR →

API reference

ProgressSteps

PropTypeDefaultDescription
currentnumberNoneFigma's Current step: the current step, from 1; earlier steps are done.
variant"numbers" | "minimal" | "icons""numbers"Figma's three sets.
orientation"auto" | "horizontal" | "vertical""auto"Figma's Direction. auto is vertical on phones and horizontal from md, since labelled steps don't fit side by side on a phone. horizontal and vertical fix it. minimal stays horizontal under auto.
numerals"latn" | "arab""latn"Numeral system for the step numbers.
aria-labelstringNoneThe flow's name for screen readers ("Account opening").

ProgressStep

PropTypeDefaultDescription
childrenReactNodeNoneFigma's Label: what people do in the step.
iconIconComponentNoneThe circle's icon in the Icons style.
hrefstringNoneA link back to a done step, to change it.

Usage guidelines

Progress steps show people where they are in an ordered flow and how much is left. When they help, which style, how to name and mark steps, layout on small screens, how they run from the right in Arabic, and the checks before handoff.

1. When steps help

Use progress steps for a flow of three to six stages that happen in a fixed order: opening an account, a checkout, delivery tracking. They answer “where am I and how much is left”. When there is no order, or only one task, other components fit better.

You need toUseWhy
Guide people through 3 to 6 ordered stagesProgress stepsShows the stage and what is left.
Track an order or a request over timeProgress steps, MinimalCompact dots with short status labels.
Show how far one task has got (an upload)Progress barOne task, a percentage.
Split content into peer sectionsTabsNo order; people jump freely.
A flow of more than 6 stagesProgress steps with grouped stagesGroup stages so people see at most six.

2. Which style

Three styles share one behavior: done steps get a check, the current step is brand colored, later steps wait in gray.

StyleUse
NumbersForms and onboarding with 3 or 4 stages; numbers show how many are left.
IconsThe same, when an icon says more than a number: ID, address, card.
MinimalUp to 6 stages in little space, such as order or delivery tracking.

3. Name and mark the steps

Name each step by what people do there, in two or three words: Personal details, Verify ID, Address, Funding. Mark a step done only once its data is saved. People can go back to done steps; skipping ahead is only allowed when the order doesn't matter.

Name what happens there

Opening an account, on the second stage.

Do: Task namesPeople know what's left: an ID check, then an address, then funding.
Don't: Numbered placeholders“Step 3” says nothing about how much work is left.

Do

  • Name steps by the task: Verify ID, not Step 2.
  • Mark a step done only after it is saved.
  • Let people return to done steps to edit them.
  • Keep step names the same as the page titles of each stage.

Don't

  • Label steps “Step 1, Step 2, Step 3”.
  • Let people jump to a later step that depends on earlier ones.
  • Change the number of steps halfway through the flow.

4. Layout and small screens

Use horizontal steps above the form on desktop. On phones, or when names are long, use the vertical direction, or show only the current step with “Step 2 of 4” and its name. Keep the steps visible while people move through the flow.

Do

  • Use horizontal steps on wide screens, vertical ones in narrow columns.
  • On phones, show “Step 2 of 4” with the current step's name.
  • Keep the steps in the same place on every stage.

Don't

  • Squeeze six horizontal steps onto a phone.
  • Hide the steps on some stages of the flow.

5. Arabic and RTL

The RTL variants run from the right: step one is on the right and progress moves left, with the connecting line filling from the right. Numbers follow the numerals setting. The check mark doesn't mirror. Arabic step names are often longer; consider the vertical direction when they wrap.

Progress runs from the right

Opening an account in Arabic, on the second stage.

Do: RTL variantStep one is on the right, done; the current step is next to its left.
Don't: English steps on an Arabic screenStep one sits on the left, so the reader sees progress running backwards.

Before handoff

  • 3 to 6 steps in a fixed order, named by task.
  • Done, current and later states are shown, and going back is designed.
  • The phone layout is decided: vertical or “Step 2 of 4”.
  • Arabic screens use RTL variants, starting from the right.

Accessibility

Keyboard

Keys are written for left-to-right. In right-to-left the arrow keys swap: the one pointing toward the reading direction moves forward.

KeyAction
TabReaches the links of done steps only; the other steps aren't interactive.

ARIA

  • An ordered ol named by the flow; the current step has aria-current="step".
  • Each step says its state in the page language: "step 2 of 4, current", not by color alone.
  • Don't mark a step done before its data is saved.

Do

  • Put aria-current="step" on the current step.
  • Say “completed” for done steps, not only a check icon.
  • Announce the position: “Step 2 of 4, Verify ID”.
  • Make done steps links or buttons when people can go back to them.

Don't

  • Rely on color alone for the current step.
  • Make later steps focusable when they can't be opened.

Arabic and RTL notes

Mirrors

  • The flow starts on the right, and the lines run to the left.
  • Vertical steps put the circles on the right with the labels to their left.

Does not mirror

  • The check and the step icons.
Numerals
Step numbers and the state text use the chosen numerals (1 2 3 or ١ ٢ ٣).
Arabic typography
body-14 for the labels, label-16 Medium for the numbers.
Mixed-direction text
Labels don't wrap in horizontal steps; keep them short.

Do

  • The RTL variant, with step one on the right.
  • Write step names natively in Arabic, and keep them short.
  • Keep the check mark as it is.

Don't

  • English steps on an Arabic screen, where progress seems to run backwards.
  • Mirror the check mark or the icons inside the circles.

Checks it passes

The Ritla checks this component satisfies by construction. Used as documented, it does not bring these defects onto your page.

  • R042Clipped text: content wider than its box with overflow hidden and no ellipsis
  • R043Fixed-pixel-width container whose Arabic text exceeds the space
  • R050Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
  • R051letter-spacing applied to Arabic text (breaks the connected script)
  • R061Arabic-Indic and Western digits mixed in the same context