Media scrubber

Seeks through media in seconds with elapsed time, buffering, chapters, and optional previews.

Preview

In action

A closer look

Three chapters · Four minutes

When to use

Use it for

A media timeline where values are seconds.
Chapter navigation or supplied thumbnail previews.

Not for

An arbitrary numeric setting; use Slider.

Install

Three ways in. They share one source, so the pixels match whichever you pick.

1. Import the package

npm install @noorddev/vlak-react

// once, next to your app's root
import "@noorddev/vlak-react/css";

import { MediaScrubber } from "@noorddev/vlak-react";

Precompiled React and one stylesheet. No compiler to configure. Per-component imports work too: @noorddev/vlak-react/components/media-scrubber.

2. Vendor the source

npx @noorddev/vlak-cli add media-scrubber

The StyleX leaf lands in components/vlak/ with its dependencies, for your own compiler to own. See StyleX.

3. Through shadcn

npx shadcn add https://vlak.dev/r/media-scrubber.json

The same registry item, installed by shadcn's CLI.

CSS only

<link rel="stylesheet" href="node_modules/@noorddev/vlak/css/vlak.css" />

No React. Link vlak.css and use the markup and classes below.

React

import { MediaScrubber } from "@noorddev/vlak-react";

<MediaScrubber value={position} duration={240} buffered={180} onValueChange={setPosition} chapters={[{ time: 0, label: "Opening" }, { time: 90, label: "The detail" }]} />

Props

formatMediaTime (function)

Elapsed media time, including hours when needed. Invalid duration is displayed as zero.

MediaScrubber

A native range in seconds with elapsed and total time. The input remains a 44px target.

Prop	Type	Default	Description
`duration`required	`number`
`label`	`string`	`"Playback position"`
`showTime`	`boolean`	`true`
`buffered`	`number`	`0`	Last buffered second.
`chapters`	`readonly MediaChapter[]`	`[]`
`preview`	`(seconds: number) => ReactNode`		Thumbnail or other visual preview for the pointed or focused second.
`value`	`number`
`defaultValue`	`number`	`0`
`step`	`number`	`1`
`onValueChange`	`(value: number) => void`

Also accepts Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "value" | "defaultValue" | "onChange">.

Keyboard

Keys	Does
`Arrow keys, Home, End`	Uses the native range input to seek within the duration.
`Tab`	Moves to the optional native chapter selector; selecting a chapter seeks to its start.

Accessibility

The range announces elapsed and total time with aria-valuetext.
Unknown or invalid duration disables seeking.
Previews are visual supplements; the native range supplies the equivalent position text.

Markup

<div class="rs-media-scrubber"><input type="range" min="0" max="240" value="42" aria-label="Playback position" aria-valuetext="0:42 of 4:00" /><div class="rs-media-scrubber-times"><span>0:42</span><span>4:00</span></div></div>

Classes

.rs-media-scrubber.rs-media-scrubber-times.rs-media-scrubber-track.rs-media-scrubber-rail.rs-media-scrubber-buffered.rs-media-scrubber-slider.rs-media-scrubber-preview.rs-media-scrubber-chapters

Depends on

/slider /native-select