Scrubber

A React component in Beamline's Form controls category, in the free sample.

A budget, a timeout or a position on a scale where the neighbourhood matters: the readout says how far under or over the named limit the value is, the ticks can be real measurements ("87% of requests at or under 90 ms"), hover shows where a press lands, a lens opens around the knob while it is held or focused (the knob never moves under it), and a release decides at once while the knob settles with the look's physics.

Use it for

Setting a limit or budget where it matters which side of it a value is on (latency, price, spend, retention).
Choosing a year, a version or a position in a history, where the values near the choice matter.

Not for

Exact values people type (number-field).
Two thumbs for a range, or a value with icons at the ends (slider).
Seeking in audio or video (scrub-bar).

Anatomy

head: label and readout (the value; with a threshold, a glyph and the distance to the named limit in words); the readout only grows while the room stays the same, so the value keeps its place; every run of words takes its own direction
well: the inset role, stretching past an end with the look's give; the zone past the threshold tinted by its tone
ticks: one per step while they keep 7 px apart; with a distribution, bars of the measured values where a value of its own sits (the lens spreads them, never changes their height)
probe: on hover, a hairline at the value a press there would set; over a mark's label it stands on that mark
rail: a native range input (keyboard, screen readers, forms) under the knob (the knob role, 3:1 boundary)
marks: labels under the well, each with a pin to its moment; their words fold by rank (the limit, then the ends, then priority); a folded mark keeps its pin
share: with a distribution, how many measured values sit at or under the value

States

rest (no lens, nothing moves)
hover (a mouse or pen shows the hairline where a press would land; nothing moves)
pressed and dragging (the lens opens around the knob, which is its fixed point and shows the step release would decide, within half a step of the pointer; it flattens while the hand moves fast; marks pull; past an end the well stretches)
settling (the value is decided; the knob glides there with the look's carry and bounce)
keyboard focus (the lens opens around the knob and follows it to each new value)
under, at and over the threshold (distance to the named limit in words, glyph and tone)
with a distribution (bars and the share at or under the value)
disabled
stacked (narrow: the readout under the label)
RTL (the scale runs from the right)

Keyboard

←/→ and ↑/↓ step, or go to the next or previous stop when `stops` is given (→ follows the reading direction)
Page Up / Page Down jump to the next or previous mark (ten steps without marks)
Home / End go to the ends
Escape while dragging puts the value back

Motion

The lens opens on the snappy spring token and closes over the fast duration, times the look's weight, centred on the knob as drawn every frame, and flattens with the hand's speed. A release decides the value at once; the knob settles on the held spring with the look's carry and bounce (only after a throw); a key or a value from outside glides over the fast duration (a value arriving mid-glide retargets it); a tap or a mark settles critically damped on the held spring. Past an end the well stretches by the look's give. Only translate and scale move; rest is plain CSS. Reduced motion: no lens, no glide, no give; the readout carries the distance and the share.

Props

Prop	Type	Default	Description
`label` (required)	`ReactNode`	—	Visible label or accessible name. Required.
`value / defaultValue / onValueChange`	`number`	—	value: The chosen value, when controlled. defaultValue: Initial value when uncontrolled; defaults to min. onValueChange: Every change of the value: each preview while dragging, and the decided value at once on release, a key or a mark. To save only what was decided, use onValueCommit.
`onValueCommit`	`(value: number) => void`	—	Once per decided change: a release, each key let go, a mark pressed, a screen reader's adjust; never a cancelled drag. Save here (debounce or confirm in the app if a save is costly).
`onValueCancel`	`(value: number) => void`	—	A drag was cancelled (Escape, a lost pointer): the value is back to `value` and nothing was committed.
`min / max / step`	`number`	—	min: Lowest value. Defaults to 0. max: Highest value. Defaults to 100. step: Increment the value moves by. Defaults to 1.
`marks`	`(number \| { value, label, priority })[]`	—	Labelled ticks; numbers, or { value, label, priority }. Page Up/Down jump between them; they pull the value like detents within 6 px of where they are drawn. When labels crowd, a higher priority keeps its words; every mark keeps its pin. A mark at the threshold's value is the threshold's own (one label, its `label`, kept before the others).
`stops`	`number[]`	—	The values the arrows step between instead of `step` (the arrivals on a timeline: one key, one event).
`threshold`	`{ value, below?, above?, label?, belowTone?, aboveTone? }`	—	A limit: the readout says how far under or over it the value is, the well past it carries its tone.
`distribution / distributionLabel / showShare`	`number[] / string / boolean`	—	distribution: Measured values along the scale (the last day's latencies): the ticks become their distribution and the readout says how many sit at or under the value. distributionLabel: What the distribution counts, for the readout ("requests" → "92 % of requests at or under 90 ms"). showShare: Shows the share at or under the value under the scale; defaults to true. False keeps the distribution as the scale only.
`format / formatOptions / prefix / suffix`	`(value) => string / Intl.NumberFormatOptions / string / string`	—	format: Turns a value into its text ("70 ms"). Wins over the plain settings below. formatOptions: Plain formatting a server component can pass: Intl options for the number. prefix: Text before the formatted number ("$"). suffix: Text after the formatted number (" ms").
`valueText`	`(value: number) => string`	—	What a screen reader hears for the value; defaults to the value, the distance to the limit and the share.
`lens`	`number`	`2.5`	How strongly the lens magnifies around the knob while it is held or has keyboard focus (0 off). Default 2.5.
`showLabel`	`boolean`	`true`	Shows the label visually while keeping its accessible name; defaults to true.
`disabled / name / dir`	`boolean / string / "ltr" \| "rtl"`	—	disabled: Prevents interaction. name: Field name for native form submission (the native range input underneath carries it). dir: Reading direction; inherits the surrounding direction when omitted.
`value`	`number`	—	The chosen value, when controlled.
`defaultValue`	`number`	—	Initial value when uncontrolled; defaults to min.
`onValueChange`	`((value: number) => void)`	—	Every change of the value: each preview while dragging, and the decided value at once on release, a key or a mark. To save only what was decided, use onValueCommit.
`min`	`number`	—	Lowest value. Defaults to 0.
`max`	`number`	—	Highest value. Defaults to 100.
`step`	`number`	—	Increment the value moves by. Defaults to 1.
`distribution`	`number[]`	—	Measured values along the scale (the last day's latencies): the ticks become their distribution and the readout says how many sit at or under the value.
`distributionLabel`	`string`	—	What the distribution counts, for the readout ("requests" → "92 % of requests at or under 90 ms").
`showShare`	`boolean`	—	Shows the share at or under the value under the scale; defaults to true. False keeps the distribution as the scale only.
`format`	`((value: number) => string)`	—	Turns a value into its text ("70 ms"). Wins over the plain settings below.
`formatOptions`	`NumberFormatOptions`	—	Plain formatting a server component can pass: Intl options for the number.
`prefix`	`string`	—	Text before the formatted number ("$").
`suffix`	`string`	—	Text after the formatted number (" ms").
`disabled`	`boolean`	—	Prevents interaction.
`name`	`string`	—	Field name for native form submission (the native range input underneath carries it).
`dir`	`"ltr" \| "rtl"`	—	Reading direction; inherits the surrounding direction when omitted.
`className`	`string`	—	Classes on the documented visual root.
`classNames`	`Partial<Record<"root" \| "label" \| "head" \| "mark" \| "tick" \| "readout" \| "zone" \| "mark…`	—	Classes for the named visual parts.
`style`	`CSSProperties`	—	Inline styles on the documented visual root.
`ref`	`Ref<HTMLDivElement>`	—	Receives the root element.

Used in

Approval policy

Import

import { Scrubber } from "@beamline/scrubber";

Get it

Scrubber is part of Beamline UI. Install the parts you need in your React app as compiled packages or editable source. Scrubber is included in the free MIT sample. Get Beamline · Connect your agent