Loading…

Step Player

beta

A stepped progress track with a play, pause and replay button: the current dot stretches into a bar that fills over its duration.

Feedback
1 file
1 npm package
Accessibility notes

Playground

Installation

One command and the file is in your project, or copy it in by hand.

$pnpm dlx @dowel-ui/cli add step-player

npm packages installed: class-variance-authority.

Usage

Imported from your own path — the file is yours, so this is an import like any other.

app/page.tsxTSX

import { StepPlayer } from "@/components/ui/step-player";

Examples

Every example the tests run, live and operable, side by side.

Default
Gallery
Playing
Loop
Seekable
Per Step Durations
Sizes
Control At End
Track Only
Driven By You
Right To Left

API

Generated from the component's own types, so a prop cannot appear here without existing.

<StepPlayer>

Prop	Type	Default
`controlLabels` Accessible names of the button in each state, for localisation.	`{ play?: string; pause?: string; replay?: string }`	—
`controlPosition` Which side of the track the button sits on.	`"start" \| "end"`	`"start"`
`defaultPlaying` Whether it starts running when uncontrolled.	`boolean`	`false`
`defaultValue` Initial step when uncontrolled. Clamped to the last step.	`number`	`0`
`duration` Milliseconds per step. 0 stops the timer so you drive `value` yourself.	`number`	`3000`
`label` Accessible name of the track.	`string`	`"Progress"`
`loop` Wrap to the first step instead of stopping. The replay button never appears.	`boolean`	`false`
`onComplete` Fires when the last step finishes — on every pass when looping.	`() => void`	—
`onPlayingChange` Fires when the button is pressed, and when the last step ends without `loop`.	`(playing: boolean) => void`	—
`onValueChange` Fires when the step advances, wraps, is chosen, or restarts on replay.	`(value: number) => void`	—
`playing` Controlled play state.	`boolean`	—
`seekable` Steps can be chosen by click, tap or keyboard.	`boolean`	`false`
`showControl` Show the round play / pause / replay button.	`boolean`	`true`
`size` Height of the track and button in pixels; everything else is a ratio of it.	`number`	`32`
`steps` How many steps, or one entry per step with its own duration and label.	`number \| StepPlayerStep[]`	`5`
`track`	`"filled" \| "plain"`	`"filled"`
`value` Controlled active step, zero-based.	`number`	—

Plus every attribute of <div> except defaultValue, onChange.

Accessibility

The round button is named for what it will do — Play, Pause or Replay (localisable with `controlLabels`) — and its icon is aria-hidden. The track is a progressbar with aria-valuetext "Step 2 of 5" (plus the step's label), or, when `seekable`, an ordered list of step buttons with aria-current="step" and a single tab stop: arrow keys (mirrored right to left), Home and End move focus and seek. Every step button's hit area is at least 24px square at any size. Nothing is announced while it plays. Timing is a requestAnimationFrame clock, so it keeps running under reduced motion, while the stretch, slide and icon morph — CSS transitions through the motion scale — become instant. Time while the page is hidden is not counted.

Quality

Measured from the source and its tests at build time.

All scores

10/10

checks passed

Tested — passes
axe assertion — passes
Keyboard tested — passes
Storybook examples — passes
Accessibility documented — passes
Semantic tokens only — passes
Motion from tokens — passes
className merged — passes
Visible focus — passes
No fixed widths — passes

Prop

Type

Default

controlLabels

Accessible names of the button in each state, for localisation.

{ play?: string; pause?: string; replay?: string }

—

controlPosition

Which side of the track the button sits on.

"start" | "end"

"start"

defaultPlaying

Whether it starts running when uncontrolled.

boolean

false

defaultValue

Initial step when uncontrolled. Clamped to the last step.

number

0

duration

Milliseconds per step. 0 stops the timer so you drive value yourself.

number

3000

label

Accessible name of the track.

string

"Progress"

loop

Wrap to the first step instead of stopping. The replay button never appears.

boolean

false

onComplete

Fires when the last step finishes — on every pass when looping.

() => void

—

onPlayingChange

Fires when the button is pressed, and when the last step ends without loop.

(playing: boolean) => void

—

onValueChange

Fires when the step advances, wraps, is chosen, or restarts on replay.

(value: number) => void

—

playing

Controlled play state.

boolean

—

seekable

Steps can be chosen by click, tap or keyboard.

boolean

false

showControl

Show the round play / pause / replay button.

boolean

true

size

Height of the track and button in pixels; everything else is a ratio of it.

number

32

steps

How many steps, or one entry per step with its own duration and label.

number | StepPlayerStep[]

5

track

"filled" | "plain"

"filled"

value

Controlled active step, zero-based.

number

—