NumberInput
React numeric input with plus and minus steppers, min, max, step, and decimal support. Holds number or null, wires label and error states, and stays LTR in Arabic.
NumberInput holds number | null. min/max clamp the value, step sizes the increment, and hideControls removes the buttons.
When to use
Use NumberInput for quantities and counts the user might nudge: number of dependents, items, or years. min and max clamp the value and step sizes each increment, which suits fees and decimal amounts.
Use TextInput with inputMode="numeric" for identifiers such as national IDs or phone numbers, because those are digits, not numbers. Set hideControls when steppers add noise in dense forms.
Examples
Props
Props declared by NumberInput. Native attributes of the underlying element pass through.
| Prop | Type | Default | Description |
|---|---|---|---|
size | "md" | "lg" | ||
variant | "default" | "filled-lighter" | "filled-darker" | ||
stepperVariant | "solid" | "subtle" | ||
value | number | Controlled value. null represents an empty field. | |
defaultValue | number | Uncontrolled initial value. | |
onValueChange | (value: number | null) => void | Fires with the parsed value, or null when the field is cleared. | |
min | number | Lower bound. Clamped on blur and at the stepper buttons. | |
max | number | Upper bound. Clamped on blur and at the stepper buttons. | |
step | number | Stepper / ArrowUp-Down increment. Defaults to 1. | |
hideControls | boolean | Hide the ＋ / − buttons (keyboard + typing only). | |
decrementLabel | string | Accessible label for the decrement button. Defaults to 'Decrease'. | |
incrementLabel | string | Accessible label for the increment button. Defaults to 'Increase'. | |
label | react.ReactNode | Visible field label, auto-associated to the input via htmlFor/id. | |
helperText | react.ReactNode | Hint shown below the field. Hidden while an error message is showing. | |
errorMessage | react.ReactNode | Message shown below the field when error is true. | |
error | boolean | Marks the field invalid: sets aria-invalid and error styling. |
Accessibility
The label, helper text, and error message are wired the same way as TextInput. The ArrowUp and ArrowDown keys change the value by step, and the stepper buttons carry accessible names.
Values are clamped rather than rejected, so users do not lose their input. Digits remain left to right inside Arabic layouts so the number reads correctly.