Scrub input

• Type: Component (inputs)
• Access: Free, open source
• Page: https://ui.xzero.co.uk/components/scrub-input
• Markdown: https://ui.xzero.co.uk/components/scrub-input/markdown
• Registry item: https://mcp.xzero.co.uk/r/scrub-input.json
• Source file: registry/components/scrub-input/scrub-input.tsx
• Dependencies: motion
• Keywords: inputs, new, react scrub input, drag to change number, scrubbable number field, inspector input, figma number input, math expression input, unit input

When to use

• Position, size, rotation, and opacity fields in an inspector panel.
• Dense settings where typing exact values and dragging both matter.
• Values with units such as px, %, or deg that people type mixed.

When not to use

• Use number-field for a normal form with stepper buttons and a visible label.
• Use slider when the range and position matter more than the exact number.
• Use money-input for currency amounts.

Installation

Register both Xzero UI namespaces in your project's components.json:

{
  "registries": {
    "@xzero-ui": "https://mcp.xzero.co.uk/r/{name}.json",
    "@xzero-ui-pro": "https://mcp.xzero.co.uk/r/pro/{name}.json"
  }
}

npx shadcn@4.23.0 add @xzero-ui/scrub-input

Install xzero-foundation once, and import @/components/xzero/foundation.css in your app root. No Xzero token is used by this snapshot. For sample portraits, photos, fonts, or logos, download https://mcp.xzero.co.uk/install-assets.mjs and run node xzero-install-assets.mjs <receiving-project>.

Usage

import { useState } from "react";
import { ScrubInput } from "@/components/xzero/scrub-input/scrub-input";

export function LayerInspector() {
  const [width, setWidth] = useState(240);
  const [opacity, setOpacity] = useState(100);
  return (
    <div style={{ display: "grid", gridTemplateColumns: "1fr 1fr", gap: 8 }}>
      <ScrubInput label="W" value={width} onValueChange={setWidth} min={0} units={["px", "%"]} resetValue={240} />
      <ScrubInput label="Opacity" value={opacity} onValueChange={setOpacity} min={0} max={100} unit="%" />
    </div>
  );
}

Examples

Rotation that wraps

<ScrubInput label="R" min={0} max={360} wrap unit="°" units={["°"]} fineStep={0.1} onValueCommit={value => setRotation(value)} />

API reference

ScrubInput

A compact number field for inspectors: drag the label to scrub, or type values with arithmetic and units, with rubber-band limits.

Prop	Type	Default	Description
label (required)	ReactNode	–	Text or a 16px icon. It is the scrub handle. Icon labels need aria-label.
value	number	–	Controlled value.
defaultValue	number	0	Starting value when uncontrolled.
onValueChange	(value: number, details: ScrubInputChangeDetails) => void	–	Fires for every change, including each scrub step. details is { source: "scrub" | "type" | "key" | "reset", unit }.
onValueCommit	(value: number, details: ScrubInputChangeDetails) => void	–	Fires once when a change settles: a scrub ends, Enter or blur commits typing, or a key step lands.
min	number	-Infinity	Lower limit.
max	number	Infinity	Upper limit.
step	number	1	One step for arrows and scrubbing.
fineStep	number	step / 10	Step with Alt held.
coarseStep	number	step * 10	Step with Shift held. Coarse steps snap to the coarse grid.
precision	number	–	Decimal places kept. Defaults to the precision of step or fineStep.
pixelsPerStep	number	2	Pointer travel in px for one step while scrubbing.
wrap	boolean	false	Wraps from max to min, as rotation does. Needs both limits.
unit	string	–	Controlled unit shown after the number. With more than one entry in units it becomes a button that cycles them.
defaultUnit	string	–	Starting unit when uncontrolled. Defaults to unit or the first of units.
units	readonly string[]	–	Units a typed value may carry, such as ["px", "%"]. Defaults to the current unit.
onUnitChange	(unit: string) => void	–	Called when a typed unit or the unit button changes the unit.
resetValue	number	–	Double click the label to return here.
track	boolean	true when min and max are set	Shows where the value sits between min and max as a quiet fill.
size	"sm" | "md"	"md"	Field height: 30px, or the small control height.
pointerLock	boolean	true	Locks the mouse pointer while scrubbing when the browser allows it.
className	string	–	Class on the root.
...props	InputHTMLAttributes<HTMLInputElement>	–	Forwarded to the input, except value, defaultValue, onChange, type, size, min, max, step, and prefix.
ref	Ref<HTMLInputElement>	–	The input element.

evaluateScrubExpression

Evaluates + - * / and parentheses over numbers that may carry a unit. Returns { value, unit? }, or null for anything else or an unknown unit.

Prop	Type	Default	Description
text (required)	string	–	The typed expression, such as "(100-24)/2" or "50%". Commas read as decimal points.
units (required)	readonly string[]	–	Allowed units. deg and ° are aliases.

Keyboard interactions

Keys	Action
ArrowUp / ArrowDown	Steps the value; Shift steps ten times coarser, Alt ten times finer.
Enter	Commits typed text, including arithmetic such as 12*2.
Escape	Restores the last value while typing, or cancels a scrub back to where it started.
Shift / Alt (while scrubbing)	Switches to coarse or fine steps mid-drag and shows the multiplier.

Accessibility

• The input is role="spinbutton" with aria-valuenow, finite aria-valuemin and aria-valuemax, and aria-valuetext that spells out percent and degrees.
• The label is a real label for the input; clicking it focuses and selects the value.
• Invalid typed text sets aria-invalid for 900ms and keeps the previous value.
• The unit cycle button is labelled Unit: <unit>. Change unit.

Motion

• Past min or max the field strains with rubber-band resistance, up to 12px, and springs back on release; the number leans with it.
• The track fill follows a drag one to one and glides to typed or stepped values.
• Invalid input and steps against a limit kick the field with a short shake; unit changes rise from a small blur.
• Reduced motion removes the strain, shake, and glide, and swaps the unit with a fade.

Responsive behavior

• The field fills its column; set --scrub-input-width to size it.
• Touch scrubs through pointer capture on the label, with touch-action: pan-y so vertical page scroll still works; pointer lock is mouse only.
• With the pointer locked, a stand-in cursor portaled to the body wraps at the window edges so a long drag never runs out of screen.

Performance

• Scrubbing writes motion values directly and emits only when the rounded value changes.
• One ResizeObserver per field tracks its width for the strain scale.

Notes for AI

• Use in design tool inspectors, property panels, and editors where people tune values by feel.
• Save on onValueCommit, not onValueChange, which fires on every scrub step.
• Set min and max for bounded values to get the track fill; set wrap for angles.
• For a labelled form field with plus and minus buttons use number-field; for a range with a thumb use slider.

Related

• Number field: Enter a bounded number with clear increment controls.
• Slider: Pick a value or a range on a track that follows your finger.
• Input: A single line field with clear labels and useful states.
• Money input: A currency field with live grouping, stable width, rolling digits, and minor-unit output.
• Color picker: A swatch that grows into a picker with format morphing, eyedropper, saved swatches, and contrast readout.

Also in special inputs

• Phone input: A phone field with a country picker, formatting as you type, and E.164 output.
• Tag input: Turn short text values into removable tags.
• Mention input: A textarea with @people and #channel mentions that act as single tokens, with suggestions at the caret.
• Shortcut recorder: Record key combinations into key caps, with conflict warnings, Kbd, and a searchable cheatsheet.

Guidance for AI tools

Scrub input: A Figma-style number field: drag the label to scrub, or type values, units, and arithmetic. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://ui.xzero.co.uk/llms.txt