Steps
Steps is a step trail for multi-step flows: a numbered badge, a connector and a label per step. It is horizontal in
wide slots and vertical in narrow ones, with the same anatomy. Only upcoming steps can act as a link or button.Navigation
When to use
Use when
- The user moves through ordered stages: onboarding, checkout, a verification-level ladder.
- The next stage is a call to action and later stages are locked.
Avoid when
- The sections have no order — use
Tabs. - You show a single percentage with no named stages — use
ProgressBar.
Usage
Each step's status comes from its position and flags. Before currentIndex (or with isComplete) it is complete; at
currentIndex it is current; with disabled it is locked. Otherwise it is next, and actionable when it has href,
to or onClick.
import { Steps } from '@apollion-dsi/core/data-display/steps';
<Steps
label="Onboarding steps"
currentIndex={2}
steps={[
{ title: 'Personal data' },
{ title: 'Documents' },
{ title: 'Proof of income' },
{ title: 'Review', href: '/onboarding/review' },
]}
/>;Locked steps
disabled locks a step that is not reachable yet: muted badge, no interaction.
<Steps
currentIndex={0}
steps={[{ title: 'Unverified' }, { title: 'Silver', href: '/user/verify' }, { title: 'Gold', disabled: true }]}
/>Router links
A step with href renders a native <a>. A step with to renders through linkAs, your router's link component.
import { Link as RouterLink } from 'react-router-dom';
<Steps linkAs={RouterLink} currentIndex={1} steps={[{ title: 'A' }, { title: 'B' }, { title: 'C', to: '/c' }]} />;Orientation
layout="auto" (the default) follows the width of the slot, not the viewport: below the md container size the trail
runs vertical, so a Steps in a narrow column goes vertical on a wide screen too. layout="desktop" and
layout="mobile" force one orientation.
StepsBadge, the numbered circle, is exported for custom layouts:
2
3
4
Accessibility
- The trail is a
<nav>named bylabel. The default name is'Etapas', so passlabelin your page's language. - The current step carries
aria-current="step"; locked steps carryaria-disabled. - The actionable step is a real link or button, reachable by keyboard; focus draws a ring around its badge.
Properties
Name
Type
Default
Description
colorstringnoneTheme token (`theme.colors`) used as `color`. Has lower precedence than
`contrast`: when both are provided, the contrast calculation wins.
Stays `string` (not the typed union): `color` is also an HTML attribute
(`<li color>`, etc.) and interfaces extending native props require
identical types on the name collision.
containmentstringnoneContainment marker for the `cq` channel: emits
`container-type` (+ `container-name` when the string form carries one,
e.g. `'inline-size card'`). Apply on the immediate wrapper of the
adapting component — NEVER on page-level shells.
counterLabel((current: number, total: number) => string)none@deprecated No longer rendered. The mobile layout is now the vertical
trail (badge + connector + label), not a progress bar with a counter, so
there is no counter string to localize. Accepted and ignored for source
compatibility; drop it — it will be removed in the next major.
currentIndexnumber00-based index of the current step.
labelstring'Etapas'Accessible name of the trail (`<nav aria-label>`).
layout"auto""desktop""mobile"'auto'Force one orientation instead of following the `md` container size.
`mobile` is the vertical trail.
legibility"on-photo"noneReading-shadow preset for text over a photographic background
(`on-photo`). Replaces the inline `style={{ textShadow }}` in the
consumer (brasil_2030 radar, gap A3). Token emission is deferred until a
2nd consumer asks for the raw var (see backlog).
lineClampnumbernoneCaps the text at this many lines and ends the cut with an ellipsis.
The full string stays in the DOM.
linkAsElementType<any, keyof IntrinsicElements>noneComponent rendered for steps with `to` (a router `Link`). Steps with
`href` always render a native `<a>`.
pageShellbooleannoneCenters the element and caps the width at `theme.layout.pageMaxWidth`.
The page shell of a classic centered layout.
readablenumberbooleannoneMakes the `color` legible against the page surface: `true` = WCAG AA
(4.5), a number sets a custom floor. Ignored with `contrast`.
See the Layout Props concept page for the full semantics.
steps *StepItem[]noneSteps, in order.
transformstringnoneCSS `transform` value (e.g. `translate(-50%, -33px)`). Never leaks
to the DOM as an attribute.