NumberInput
Edit a constrained number with step buttons and keyboard controls.
Anatomy#
This is the horizontal layout. A vertical layout wraps the buttons in a controls slot after the input.
Usage#
Use NumberInput for a numeric field with step controls and constrained committed values. Use a plain Input when free-form numeric text is required, and Slider when the value is chosen spatially.
Values and boundaries#
value, defaultValue, and onValueChange all use number | undefined. value={undefined} keeps
the input uncontrolled. Display text comes from locale (default: the provider locale, then
en-US) and formatOptions, so the value stays a plain number. Clearing the input emits
undefined. Typing commits as soon as the text is a complete number; partial text such as - waits
for blur or Enter. Committed, stepped, and controlled values are clamped to min and max.
onValueChange does not fire when the value is unchanged. Decimal steps are calculated to avoid
typical floating-point display noise.
Set name to submit the plain number through a hidden input, and form to associate the control
with a <form> outside its ancestors.
Stepping and repeat#
The default layout is horizontal: decrement button, input, increment button. With
orientation="vertical", both buttons move into a controls wrapper after the input. Either way,
the input stays the spinbutton keyboard target. increment={false} or decrement={false} hides a
button, and incrementDisabled or decrementDisabled disables it without blocking keyboard or
wheel stepping. A button is also disabled at max or min.
step (default 1) sets the amount for the buttons, ArrowUp and ArrowDown, and the mouse wheel.
largeStep (default step * 10) sets the amount for PageUp and PageDown, and for the wheel while
Shift is held. By default stepping lands on the step grid anchored at min (or at 0 without
min), so step={5} from 7 goes to 10; set stepSnapping={false} to step from the exact
value. Typed values are clamped, never snapped. The wheel steps only when wheel is set and the
input is focused.
Hold-to-repeat on the buttons is enabled by default. Tune it with
repeat={{ delay, interval, throttle, pointerTypes }} (defaults 500, 80, 0, and 'all';
interval has a floor of 16 ms) or disable it with repeat={false}.
Keyboard interaction#
Keys have no effect while the control is disabled or read-only.
| Key | Description |
|---|---|
| ↑ | Increments the value by step. |
| ↓ | Decrements the value by step. |
| ⇞ | Increments by largeStep (defaults to step * 10). |
| ⇟ | Decrements by largeStep (defaults to step * 10). |
| ↖ | Sets the value to min when min is set. |
| ↘ | Sets the value to max when max is set. |
| ↵ | Commits the typed text as a number. |
Examples#
Set a cart quantity#
Keep the count in local state with onValueChange. Bound it with min and max.
Edit a retry delay#
Use step for the arrow keys and largeStep for PageUp and PageDown. Home and End jump to the
min and max bounds.
Hold to change a count#
Hold-to-repeat is on by default. Tune it with repeat={{ delay, interval, throttle, pointerTypes }}
or pass repeat={false} to step once per click.
Bind a numeric field#
Place NumberInput in form.Field so the schema owns the committed number.
API Reference#
Attributes#
data-disableddata-invaliddata-readonlydata-requireddata-auto-aligndata-activeProps#
Props for the NumberInput component. Renders a <div> element by default.