Scrub bar

A React component in Beamline's Voice & audio category.

A seekable timeline for audio or video: elapsed and total time, what has loaded, chapter marks, a time preview under the pointer, and the full keyboard of a media slider.

Use it for

The position control of a custom audio or video player.
Seeking inside a recording with chapter or speaker marks.

Not for

Choosing a value on a scale (slider).
Showing how far a task has got (progress).

Anatomy

elapsed time
track (an inset well: the loaded run, the played run as a solid, chapter ticks)
thumb (the knob; shown under the pointer, on focus and while held)
playhead (instead of the thumb when the track is a waveform)
time preview under the pointer
total time

Variants

size: sm, md

States

idle
hover (track thickens, preview time)
scrubbing (pointer held)
focused
unknown length (hatched, not seekable)
disabled (the whole bar at the disabled opacity, no thumb)

Keyboard

← / → seek by `step` (5 s; mirrored in RTL)
↑ / ↓ the same
Page Up / Page Down seek a tenth of the length
Home / End go to the start / the end
Space or K play and pause (with onTogglePlay)

Motion

The played part is a transform, so following playback costs no layout. The thumb grows on hover at 0 ms and settles back over --pui-motion-out; nothing moves under reduced motion except the position itself.

Props

Prop	Type	Default	Description
`value / defaultValue / onValueChange`	`number`	—	Position in seconds; changes while scrubbing.
`onValueCommit`	`(seconds: number) => void`	—	When the pointer lets go or a key seeks: seek the media here.
`duration` (required)	`number \| null`	—	Length in seconds; null while unknown (the track is hatched and inert).
`buffered`	`number`	—	Seconds loaded from the start.
`markers`	`{ time: number; label: string }[]`	—	Chapter or speaker marks on the track; their labels show in the preview.
`step`	`number`	`5`	Seconds per arrow key.
`format`	`(seconds: number) => string`	`m:ss`
`showTime`	`boolean`	`true`	Elapsed and total time at the ends.
`onTogglePlay`	`() => void`	—	Space and K on the bar play or pause.
`onScrubbingChange`	`(scrubbing: boolean) => void`	—	Pause following playback while true.
`label`	`string`	`"Seek"`
`size`	`"sm" \| "md"`	`"md"`
`disabled`	`boolean`	—
`classNames`	`ScrubBarClassNames`	—
`style / ref`	`CSSProperties / native Ref`	—

Import

import { ScrubBar } from "@/components/scrub-bar/scrub-bar";

Get it

Scrub bar is part of Beamline: 190 React components and screens your coding agent (Claude Code, Codex, Cursor or any MCP client) installs into your app through Beamline's MCP server, as a ready-built package or as plain React source you can change. $49 one payment (regular $200), no subscription, a year of updates, one licence for your whole team. Get Beamline · Connect your agent