Value grip

A React component in Beamline's Form controls category.

A grip on a scale your screen draws (a bar's end, a flag, a markup's edge): drag it, or use the arrows, to a value snapped to its step; the value arrives live while held and is committed once on letting go, Escape puts back the value from the press, and screen readers hear it as a slider with the value in your words.

Use it for

A quantity your screen already draws (a lead time on a runway, a markup on a cost bar, a deadline flag): make the drawing the control instead of a typed field, with the field kept as the exact twin.
Several grips on one drawing that each move their own value, with the scale held still while one is held.

Not for

A stand-alone range input with its own track (slider).
Scrubbing through time or a recording (scrubber, replay-bar).
Moving whole items between places (drag-and-drop lists, kanban-board).

Anatomy

handle: spans the host's track and is moved to the value by transform
thumb (role slider): a 24 px hit on the value (44 px under a finger), drawn as an upright ink bar (bar) or only as its hover and focus (bare, over a mark the host draws)

States

rest: placed by CSS from the value
hover: a ring around the bar, or a tint over a bare mark
focus: the focus ring on the thumb
held (data-state=held): no glide, the value follows the hand per step; the host is told (onHoldChange) to hold its scale still
released: onValueCommit once
cancelled (Escape, a lost pointer): the value from the press comes back through onValueChange, no commit
keyboard step: onValueChange and onValueCommit together
disabled: no hand, not in the tab order
right to left: the scale and the arrow keys mirror
reduced motion: no glide after a key or a commit

Keyboard

Left/Right (mirrored right to left) and Down/Up: one step
Shift with an arrow, or Page Up/Down: the big step
Home/End: the limits
Escape during a drag: back to the value at the press

Motion

Between values set by a key or by the host the handle glides by transform with the considered duration; while held it follows the hand in the same frame (no transition). Nothing runs at rest; reduced motion places it at once.

Props

Prop	Type	Default	Description
`value` (required)	`number`	—	The value the grip stands on, in the scale's units (days, dollars, a rate).
`scale` (required)	`{ from: number; to: number; }`	—	What the track's start and end stand for. The grip is placed at `(value - from) / (to - from)` of the track. Hold the scale still while the grip is held (`onHoldChange`), so nothing under the hand moves.
`track` (required)	`RefObject<HTMLElement \| null>`	—	The element the scale is drawn across; read once at the press, never during the drag.
`step`	`number`	—	Units per step (7 for a week of days, 0.5 for half a percent). Default 1.
`bigStep`	`number`	—	Units per Shift step and Page Up/Down. Default 10 steps.
`origin`	`number`	—	Where steps count from (a lead time's start): values snap to `origin + n × step`. Default 0.
`min` (required)	`number`	—
`max` (required)	`number`	—
`label` (required)	`string`	—	The grip's name ("Lead time", "Markup on labour").
`valueText`	`string`	—	The value in words, with what it does ("9 weeks: arrives Jan 23, 1 day late"). Default: the number.
`onValueChange`	`((value: number) => void)`	—	Every step while held, and every key step: redraw from it.
`onValueCommit`	`((value: number) => void)`	—	Once, on letting go or after a key step: save it. Not called on Escape.
`onHoldChange`	`((held: boolean) => void)`	—	Held or let go: freeze the scale and stop gliding while held.
`appearance`	`"bar" \| "bare"`	—	`bar` draws an upright ink bar on the value (a bar's end); `bare` draws nothing but the hover and focus (the host already draws a mark there, such as a flag). Default bar.
`disabled`	`boolean`	—
`className`	`string`	—	Classes on the documented visual root; no override by default.
`style`	`CSSProperties`	—	Inline styles on the documented visual root; no overrides by default.
`ref`	`Ref<HTMLSpanElement>`	—	Receives the documented native target or imperative handle; omitted by default.

Used in

Import

import { ValueGrip } from "@beamline/value-grip";

Get it

Value grip is part of Beamline UI. Install the parts you need in your React app as compiled packages or editable source. Get Beamline · Connect your agent