| align | "start" | "end" | "start" | Right-align the number (amount columns). |
| className | string | — | Classes for the root (label + control + help). |
| controlClassName | string | — | Classes for the bordered control. |
| description | ReactNode | — | One short sentence of help under the control. |
| errorMessage | string | ((validation: ValidationResult) => string) | — | Error text shown while the field is invalid (or a function of the validation result). |
| inputMode | "none" | "text" | "tel" | "url" | "email" | "numeric" | "decimal" | "search" | — | Software keyboard on touch devices. Default: `decimal` when the format allows
fractions, else `numeric` — chosen from the format, never the device, so the
server and the browser render the same attribute (React Aria's device-based
choice breaks hydration on phones and then sticks). |
| label | ReactNode | — | Visible label. Omit only when an `aria-label` names the field. |
| placeholder | string | — | Placeholder shown while empty. |
| showStepper | boolean | false | Show − / + buttons. Off by default; arrow keys and the wheel still step. |
| size | FieldSize | "md" | `md` 32px (default) or `compact` 28px for tables and toolbars. |
| autoFocus | boolean | — | Whether the element should receive focus on render. |
| decrementAriaLabel | string | — | A custom aria-label for the decrement button. If not provided, the localized string "Decrement"
is used. |
| defaultValue | number | — | The default value (uncontrolled). |
| form | string | — | The `<form>` element to associate the input with.
The value of this attribute must be the id of a `<form>` in the same document.
See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form). |
| incrementAriaLabel | string | — | A custom aria-label for the increment button. If not provided, the localized string "Increment"
is used. |
| isDisabled | boolean | — | Whether the input is disabled. |
| isInvalid | boolean | — | Whether the input value is invalid. |
| isReadOnly | boolean | — | Whether the input can be selected but not changed by the user. |
| isRequired | boolean | — | Whether user input is required on the input before form submission. |
| isWheelDisabled | boolean | — | Enables or disables changing the value with scroll. |
| maxValue | number | — | The largest value allowed for the input. |
| minValue | number | — | The smallest value allowed for the input. |
| name | string | — | The name of the input element, used when submitting an HTML form. See
[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
| onChange | ((value: number) => void) | — | Handler that is called when the value changes. |
| render | DOMRenderFunction<"div", NumberFieldRenderProps> | — | Overrides the default DOM element with a custom render function.
This allows rendering existing components with built-in styles and behaviors
such as router links, animation libraries, and pre-styled components.
Requirements:
- You must render the expected element type (e.g. if `<button>` is expected, you cannot render an
`<a>`).
- Only a single root DOM element can be rendered (no fragments).
- You must pass through props and ref to the underlying DOM element, merging with your own prop
as appropriate. |
| step | number | — | The amount that the input value changes with each increment or decrement "tick". |
| validate | ((value: number) => ValidationError | true) | — | A function that returns an error message if a given value is invalid.
Validation errors are displayed to the user when the form is submitted
if `validationBehavior="native"`. For realtime validation, use the `isInvalid`
prop instead. |
| validationBehavior | "native" | "aria" | 'native' | Whether to use native HTML form validation to prevent form submission
when the value is missing or invalid, or mark the field as required
or invalid via ARIA. |
| value | number | — | The current value (controlled). |