Skip to content
flyingsalmon

Stepper

A display-only bar of equal segments, filled through the current one, for a position in a sequence whose length is known.

Planning your tripQuestion 2 of 4

Next: who is travelling with you

Installation

npx shadcn@latest add @flyingsalmon/stepper

Usage

import { Stepper } from '@/components/ui/stepper'

export function StepperUsage() {
  return <Stepper count={4} current={2} label="Trip questions" />
}

Examples

Forward and back

Press Next and Back. Advancing fills the reached segment from its left edge, and going back empties it.

Question 1 of 4

A growing count

Ask a follow-up and the count grows while the bar is mounted. The new segment appears as upcoming with no enter animation.

Question 2 of 3

Guidelines

When to use

  • To show where someone is in a sequence they are walking: question 2 of 4 while the AI plans a trip.
  • When the count is known and every step weighs about the same, so ticks say more than a fraction would.

When not to use

  • Use Progress for how far one operation has got, such as an upload. A bar of a machine working is a fraction, not a position.
  • Use Timeline for a series of events that each carry their own content, because the stepper has no markers and no labels.
  • Use Tabs to let the traveller jump between peer panels, because the stepper is never interactive.
  • Use Pagination to move between the numbered pages of a list.

Do and don’t

  • Do
    Name the current step in words with the bar, under it or beside it.The bar carries no words and paints the current step the same as the ones already done, so the name is what tells the traveller where they are.
  • Do
    Put the bar inside the card that explains the step, one bar per surface.The card’s title says what is happening and the bar says how far along it is. Two bars on one surface make the traveller ask which one is theirs.
  • Don’t
    Use the bar as a control for going back or skipping ahead.It has no hover, no focus, and no tab stop. Back and Next buttons beside it move the traveller, or the app advances on its own.
  • Don’t
    Fill part of a segment to show partial progress.A step is either reached or not. Partial progress inside a step is a progress bar’s job.
  • Don’t
    Colour the bar to show that a step failed.The bar only ever shows position. A failure replaces the card around it with an error state and a retry, where the traveller is already looking.

Accessibility

The bar is not interactive: nothing in it takes focus, so there is no keyboard path. It is a list named by label, which defaults to “Progress”. Each segment is a listitem named “2 of 4”, and the current one carries aria-current="step", so a screen reader reads “2 of 4, current step”. Give each bar a label that says what the steps are.

API

Stepper

Draws segments only, with no text slots and no segment labels: map your own notion of a step onto count and current, and write the step’s name yourself. Also takes every <div> attribute.

PropTypeDefaultDescription
countnumberRequiredThe number of segments. It may change while mounted.
currentnumberRequiredThe current step, counting from 1. Values outside 1 to count are clamped.
labelstring"Progress"The accessible name of the list.

  • Progress

    A fraction of one operation with a known end.
  • Timeline

    Markers joined by connectors, each with its own content.
  • Tabs

    Navigation between peer panels.
  • Number field

    Where the minus and plus spin buttons live.