# Scrub bar

A React component in [Beamline](https://beamline.io/)'s [Voice & audio](https://beamline.io/components/voice) category. Live demo: https://beamline.io/components/scrub-bar

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](https://beamline.io/components/slider)).
- Showing how far a task has got ([progress](https://beamline.io/components/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

```tsx
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](https://beamline.io/checkout?pack=complete) · [Connect your agent](https://beamline.io/connect)

## More in Voice & audio

- [Audio player](https://beamline.io/components/audio-player): One audio element and its controls: play with a loading state, a scrub bar with time, skip, speed and a playlist whose rows play into the same player…
- [Bar visualizer](https://beamline.io/components/bar-visualizer): A row of bars that says what a voice agent is doing: a sweep while connecting, the person's voice while listening, a slow breath while thinking, the…
- [Conversation bar](https://beamline.io/components/conversation-bar): The control bar of a voice call with an agent: one button to call and hang up, the agent's state as bars, a call timer, mute, and typing when talking is…
- [Live waveform](https://beamline.io/components/live-waveform): Loudness drawn as it happens: a scrolling history of the microphone (or any live source) or its spectrum, a calm processing state while words are…
- [Matrix](https://beamline.io/components/matrix): A dot-matrix display: animated frame sets (loading, pulse, wave, syncing), text and digits in a 5×7 font, or a VU meter of levels or a live source. One…
- [Microphone selector](https://beamline.io/components/mic-selector): Choose the microphone, test it with a live level and mute it, with every permission and device state spelled out: not yet allowed, blocked (and how to…
- [Orb](https://beamline.io/components/orb): The agent's presence: a thin ring of light around a lens in the brand's hue that holds still at rest, sends an arc round while thinking and widens with…
- [Speech input](https://beamline.io/components/speech-input): A text field you can speak into: the mic dictates through any speech-to-text provider, the phrase being heard shows apart from the finished words, and…
- [Transcript viewer](https://beamline.io/components/transcript-viewer): A recording and its words together: the spoken word lights up as it plays and the transcript follows it, any word or paragraph time plays from there…
- [Voice button](https://beamline.io/components/voice-button): The control that starts and stops talking: click to toggle or hold to talk (pointer, Space, Enter or a global shortcut), with a live level while…
- [Voice picker](https://beamline.io/components/voice-picker): Choose a text-to-speech voice from a searchable list (name, accent, tone, use) and hear it first: each voice has its own orb, previews play one at a time…
- [Waveform](https://beamline.io/components/waveform): The shape of a recording: one bar per slice of loudness, fitted to any width, with the played part in the accent, unmeasured slices hatched and a loading…