Progress Steps
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
Preview
Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.
Installation
Add the component
npx ritla add progress-stepsAlso works with shadcn:
npx shadcn@latest add @ritla/progress-stepsDependencies it brings
@phosphor-icons/reactOr 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
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
API reference
ProgressSteps
| Prop | Type | Default | Description |
|---|---|---|---|
current | number | None | Figma'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-label | string | None | The flow's name for screen readers ("Account opening"). |
ProgressStep
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | None | Figma's Label: what people do in the step. |
icon | IconComponent | None | The circle's icon in the Icons style. |
href | string | None | A 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 to | Use | Why |
|---|---|---|
| Guide people through 3 to 6 ordered stages | Progress steps | Shows the stage and what is left. |
| Track an order or a request over time | Progress steps, Minimal | Compact dots with short status labels. |
| Show how far one task has got (an upload) | Progress bar | One task, a percentage. |
| Split content into peer sections | Tabs | No order; people jump freely. |
| A flow of more than 6 stages | Progress steps with grouped stages | Group 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.
| Style | Use |
|---|---|
| Numbers | Forms and onboarding with 3 or 4 stages; numbers show how many are left. |
| Icons | The same, when an icon says more than a number: ID, address, card. |
| Minimal | Up 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
- 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.
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.
| Key | Action |
|---|---|
| Tab | Reaches the links of done steps only; the other steps aren't interactive. |
ARIA
- An ordered
olnamed by the flow; the current step hasaria-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-14for the labels,label-16Medium 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.
- Clipped text: content wider than its box with overflow hidden and no ellipsis
- Fixed-pixel-width container whose Arabic text exceeds the space
- Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
- letter-spacing applied to Arabic text (breaks the connected script)
- Arabic-Indic and Western digits mixed in the same context