Fair Case

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.

Housing, the first step
Work
Family

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.

Paused: 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

Variants
PropValueHow it looks
capsulegroupInline 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.
dotsinactive8px dots, 16px apart, in the dot colour (ink 34% light, ground 35% dark). Each has a 24px square tap area.
dotsactiveA 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.
buttonpause or playAn IconButton, variant control, size responsive: 44px below 768px, 32px from 768px. PauseIcon or PlayIcon, solid glyphs at 16px.

States

States
StateHow it looks
playingdata-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.
pauseddata-state is paused. The fill stops in place and keeps its progress, and the button shows PlayIcon.
heldMouse 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 motionNever starts on its own. The visitor's own play choice still works.
before mountThe server render and first paint show a still stepper. Autoplay starts once the client knows the motion preference.
dot hoverAn inactive dot takes the muted colour (#4A5D72 light, #9FB3C8 dark).
focusA 2px focus outline at a 2px offset on the dot. Arrow keys follow the reading direction, and Home and End go to the ends.
pressednot written for the dots

Props

Import from @repo/ui/stepper.

Props
PropTypeDefaultWhat it does
stepsstring[]default requiredOne accessible name per step, such as the topic of each photo.
indexnumberdefault requiredThe step showing.
onIndexChange(index: number) => voiddefault requiredCalled when a dot is clicked, a key moves, or the fill ends.
labelstringdefault requiredNames the tab list, for example "Photos". Also the group's aria-label.
pauseLabelstringdefault requiredThe pause button's name while playing.
playLabelstringdefault requiredThe play button's name while paused.
controlsstring | undefinedThe id of the region the steps change, for aria-controls on each tab.
heldbooleandefault falseHolds autoplay while true, such as while the visitor types.
pausedboolean | undefinedThe 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) => voidCalled when the pause button is pressed.
durationMsnumberdefault 6000How long each step's fill runs.
classNamestring | undefinedExtra 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.