Stepper
Dots that autoplay through steps and loop, with a pause button. The dots are tabs named after their steps, and they are the only way to step. Autoplay holds while the stepper is hovered or focused, while held is set and while the tab is hidden.
Steps
Three steps, held so nothing advances. The active dot is a 24px pill whose fill runs over 6 seconds. The button is 32px from 768px and 44px below it.
TSX
const [index, setIndex] = useState(0);
<Stepper
steps={["Housing", "Work", "Family"]}
index={index}
onIndexChange={setIndex}
label="Photos"
pauseLabel="Pause photos"
playLabel="Play photos"
held
/>Paused
The fill stops in place and keeps its progress, and the button shows Play.
TSX
<Stepper
steps={["Housing", "Work", "Family"]}
index={1}
onIndexChange={setIndex}
label="Photos"
pauseLabel="Pause photos"
playLabel="Play photos"
paused
/>On the site
On the site the stepper advances every 6 seconds and loops. It holds while the pointer is over it or focus is in it, and while the page is in a hidden tab. Under reduced motion it never starts on its own.
Code
TSX
<Stepper
steps={["Housing", "Work", "Family"]}
index={index}
onIndexChange={setIndex}
label="Photos"
pauseLabel="Pause photos"
playLabel="Play photos"
held
/>From stepper.stories.tsx. held stops autoplay, so a story never advances on its own. The hero passes held={askHeld || hovered || drag !== null || !controlsShown} and its own paused state (hero.tsx).
Variants
| Prop | Value | How it looks |
|---|---|---|
| capsule | group | Inline pill with a 1px rule border (#B2D5FF light, #23446A dark), the overlay fill (ground 72% light, dark-ground 55% dark) and a small backdrop blur. 16px padding at the start, 6px at the end, top and bottom, 12px between the dots and the button. |
| dots | inactive | 8px dots, 16px apart, in the dot colour (ink 34% light, ground 35% dark). Each has a 24px square tap area. |
| dots | active | A 24px wide pill in the track tone (ink 14% light, ground 18% dark) with the fill running inside it in the signal colour (#0D84FF light, #7EB7FF dark), over 6000ms by default. |
| button | pause or play | An IconButton, variant control, size responsive: 44px below 768px, 32px from 768px. PauseIcon or PlayIcon, solid glyphs at 16px. |
States
| State | How it looks |
|---|---|
| playing | data-state is playing. The active pill fills from the start edge; the fill's end advances to the next step, and the last step loops to the first. |
| paused | data-state is paused. The fill stops in place and keeps its progress, and the button shows PlayIcon. |
| held | Mouse hover, keyboard focus in the stepper, held set or a hidden tab: the fill pauses in place. A step that came due while held advances when autoplay runs again. |
| reduced motion | Never starts on its own. The visitor's own play choice still works. |
| before mount | The server render and first paint show a still stepper. Autoplay starts once the client knows the motion preference. |
| dot hover | An inactive dot takes the muted colour (#4A5D72 light, #9FB3C8 dark). |
| focus | A 2px focus outline at a 2px offset on the dot. Arrow keys follow the reading direction, and Home and End go to the ends. |
| pressed | not written for the dots |
Props
Import from @repo/ui/stepper.
| Prop | Type | Default | What it does |
|---|---|---|---|
| steps | string[] | default required | One accessible name per step, such as the topic of each photo. |
| index | number | default required | The step showing. |
| onIndexChange | (index: number) => void | default required | Called when a dot is clicked, a key moves, or the fill ends. |
| label | string | default required | Names the tab list, for example "Photos". Also the group's aria-label. |
| pauseLabel | string | default required | The pause button's name while playing. |
| playLabel | string | default required | The play button's name while paused. |
| controls | string | undefined | The id of the region the steps change, for aria-controls on each tab. | |
| held | boolean | default false | Holds autoplay while true, such as while the visitor types. |
| paused | boolean | undefined | The visitor's play or pause choice, when the caller keeps it (a swipe that pauses). When left out, the stepper keeps it itself. | |
| onPausedChange | (paused: boolean) => void | Called when the pause button is pressed. | |
| durationMs | number | default 6000 | How long each step's fill runs. |
| className | string | undefined | Extra classes on the group. |
Use it well
The dots are tabs named after their steps. Nothing is announced on an automatic advance.
Pass held while the visitor is doing something else: the hero passes it while the Ask box is in use or a drag runs.
A pause keeps its progress because the fill is a CSS animation (stepper-fill), not a transition.
Each dot's tap area is 24px square, and none overlaps its neighbour (WCAG 2.5.8).
Wrap the page in TooltipProvider: the pause button is an IconButton with a tooltip.