NumberInput

Blender-style numeric input designed for professional editor interfaces. Supports drag-to-scrub value changes, increment/decrement step buttons, mathematical expression evaluation, and modifier keys for precision and large-step adjustments.

Live Preview

Import

import { NumberInput } from 'entangle-ui';

Usage

const [value, setValue] = useState(0);

<NumberInput value={value} onChange={setValue} />;

Drag to Scrub

Click and drag left/right on the input to scrub the value. This is the signature interaction from Blender-style editors. Short clicks enter edit mode for direct keyboard input.

<NumberInput value={rotation} onChange={setRotation} unit="°" step={1} />

Modifier keys during drag:

• Ctrl held: large step increments (default step * 10)
• Shift held: precision step increments (default step / 10)

Unit Display

The unit prop displays a suffix next to the value. It can be a static string or a function that formats based on the current value.

// Static unit
<NumberInput value={width} onChange={setWidth} unit="px" />

// Dynamic unit
<NumberInput
  value={progress}
  onChange={setProgress}
  unit={(v) => `${(v * 100).toFixed(0)}%`}
/>

Limits

Use min and max for hard limits (cannot be exceeded). Use softMin and softMax for drag limits that can still be overridden by typing values directly.

<NumberInput
  value={opacity}
  onChange={setOpacity}
  min={0}
  max={1}
  step={0.01}
  precision={2}
/>

// Soft limits — drag stops at 0-100, but keyboard allows wider range
<NumberInput
  value={temperature}
  onChange={setTemperature}
  softMin={0}
  softMax={100}
  min={-273}
  max={1000}
/>

Expression Support

When allowExpressions is enabled (default), users can type mathematical expressions into the input. Supported functions include pi, sqrt, sin, cos, tan, abs, and basic arithmetic.

<NumberInput
  value={angle}
  onChange={setAngle}
  allowExpressions
  placeholder="Enter value or expression"
/>

A user could type 360/7 or pi * 2 and the expression will be evaluated.

Sizes

Sizes are optimized for editor interface density.

<NumberInput value={v} onChange={setV} size="sm" label="Small" />
<NumberInput value={v} onChange={setV} size="md" label="Medium" />
<NumberInput value={v} onChange={setV} size="lg" label="Large" />

| Size | Height | Use case | | ---- | ------ | ---------------- | | sm | 20px | Compact toolbars | | md | 24px | Standard panels | | lg | 32px | Prominent inputs |

Custom Formatting

Use formatValue and parseValue for custom display formatting such as currency or comma-separated numbers.

<NumberInput
  value={price}
  onChange={setPrice}
  formatValue={v => `$${v.toFixed(2)}`}
  parseValue={s => {
    const n = parseFloat(s.replace(/[$,]/g, ''));
    return isNaN(n) ? null : n;
  }}
/>

Validation

Provide a validate function that returns an error message string if the value is invalid, or undefined if valid.

<NumberInput
  value={dimension}
  onChange={setDimension}
  validate={v => (v <= 0 ? 'Must be positive' : undefined)}
/>

Labels and Helper Text

<NumberInput
  value={x}
  onChange={setX}
  label="X Position"
  helperText="World-space X coordinate"
  required
/>

Error State

<NumberInput
  value={v}
  onChange={setV}
  errorMessage="Value out of range"
  label="Scale"
/>

Disabled and Read-Only

<NumberInput value={42} onChange={() => {}} disabled label="Disabled" />
<NumberInput value={42} onChange={() => {}} readOnly label="Read-only" />

Props

Prop	Type	Default	Description
value	number	—	Current numeric value.
onChange	(value: number) => void	—	Callback when value changes.
unit	string | ((value: number) => string)	—	Unit suffix to display (e.g., "px", "%", "deg"). Can be a function for dynamic formatting.
showStepButtons	boolean	true	Whether to show increment/decrement chevron buttons on hover.
validate	(value: number) => string | undefined	—	Custom validation function. Return error message string if invalid.
formatValue	(value: number) => string	—	Format value for display (e.g., add commas, currency symbols).
parseValue	(input: string) => number | null	—	Parse custom formatted input back to number. Used with formatValue.
min	number	—	Minimum allowed value (hard limit).
max	number	—	Maximum allowed value (hard limit).
softMin	number	—	Soft minimum for drag operations. Can be overridden by keyboard input.
softMax	number	—	Soft maximum for drag operations. Can be overridden by keyboard input.
step	number	1	Step size for increment/decrement and drag operations.
precisionStep	number	step / 10	Step size when Shift is held (precision mode).
largeStep	number	step * 10	Step size when Ctrl is held (large steps).
precision	number	—	Number of decimal places for display.
allowExpressions	boolean	true	Whether to allow mathematical expression input (pi, sqrt, sin, etc.).
dragSensitivity	number	1	Sensitivity multiplier for mouse drag scrubbing.
size	'sm' | 'md' | 'lg'	'md'	Input size variant.
disabled	boolean	false	Whether the input is disabled.
readOnly	boolean	false	Whether the input is read-only.
errorMessage	string	—	Error message displayed below the input.
placeholder	string	—	Placeholder text shown in edit mode.
label	string	—	Input label displayed above the field.
helperText	string	—	Helper text displayed below the input.
required	boolean	false	Whether the input is required.
onFocus	(event: FocusEvent) => void	—	Focus event handler.
onBlur	(event: FocusEvent) => void	—	Blur event handler.
onKeyDown	(event: KeyboardEvent) => void	—	Key down event handler.
className	string	—	Additional CSS class names.
testId	string	—	Test identifier for automated testing.
ref	Ref<HTMLInputElement>	—	Ref to the underlying input element.

Accessibility

• Click-to-edit distinguishes between short clicks (enter edit mode) and drag gestures (scrub value)
• Step buttons have aria-label attributes (“Increment value” / “Decrement value”)
• Step buttons are hidden from tab order (tabIndex={-1}) to keep focus on the main input
• label prop renders a <label> element associated with the input via htmlFor
• Required fields show a visual indicator and set required on the input
• Error states are communicated through helper text below the input
• Keyboard: Arrow Up/Down for step, Shift+Arrow for precision, Ctrl+Arrow for large steps, Enter to confirm, Escape to cancel