Example
Related
- TextField — Use for typical text input.
Formatting
The NumberField value can be formatted by using the formatOptions prop, which is compatible with the option parameter of Intl.NumberFormat and is applied based on the current locale.
Decimals
The following example uses the signDisplay option to include the plus sign for positive numbers, for example to display an offset from some value. In addition, it always displays a minimum of 1 digit after the decimal point, and allows up to 2 fraction digits. If the user enters more than 2 fraction digits, the result will be rounded.
Percentages
The style of "percent" can be passed to the formatOptions prop to treat the value as a percentage. In this mode, the value is multiplied by 100 before it is displayed, i.e. 0.45 is displayed as 45%. The reverse is also true: when the user enters a value, the onChange event will be triggered with the entered value divided by 100.
When the percent option is enabled, the default step automatically changes to 0.01 such that incrementing and decrementing occurs by 1%. This can be overridden with the step prop.
Currency
The style of "currency" can be passed to the formatOptions prop to treat the value as a currency value. The currency option must also be passed to set the currency code (e.g. AUD) to use. In addition, the currencyDisplay option can be used to choose whether to display the currency symbol, currency code, or currency name. Finally, the currencySign option can be set to "accounting" to use accounting notation for negative numbers, which uses parentheses rather than a minus sign in some locales.
If you need to allow the user to change the currency, you should include a separate control. The NumberField will not determine the currency from the user input.
Units
The style of "unit" can be passed to the formatOptions prop to format the value with a unit of measurement. The unit option must also be passed to set which unit to use (e.g. "centimeter"). In addition, the unitDisplay option can be used to choose whether to display the unit in long, short, or narrow format.
If you need to allow the user to change the unit, you should include a separate control. The NumberField will not determine the unit from the user input.
Props
Min and Max
The minValue and maxValue props can be used to limit the entered value to a specific range. The value will be clamped when the user blurs the input field. In addition, the increment and decrement buttons will be disabled when the value is within one step value from the bounds.
Ranges can be open ended by only providing either minValue or maxValue rather than both. If a valid range is known ahead of time, it is a good idea to provide it so the experience can be optimised. For example, when the minimum value is greater than or equal to zero, it is possible to use a numeric keyboard on iOS rather than a full text keyboard (necessary to enter a minus sign).
Step
The step prop can be used to snap the value to certain increments. If there is a minValue defined, the steps are calculated starting from the minimum. For example, if minValue={2}, and step={3}, the valid step values would be 2, 5, 8, 11, etc. If no minValue is defined, the steps are calculated starting from zero and extending in both directions. In other words, such that the values are evenly divisible by the step. A step can be any positive decimal. If no step is defined, any decimal value may be typed, but incrementing and decrementing snaps the value to an integer.
If the user types a value that is between two steps and blurs the input, the value will be snapped to the nearest step. When incrementing or decrementing, the value is snapped to the nearest step that is higher or lower, respectively. When incrementing or decrementing from an empty field, the value starts at the minValue or maxValue, respectively, if defined. Otherwise, the value starts from 0.
Label
Every number field must have a label.
If you do not provide a visible label, you must specify an aria-label or aria-labelledby attribute for accessibility.
Description
The description communicates a hint or helpful information, such as specific requirements for correctly filling out the field.
Error message
The errorMessage communicates validation errors when field requirements aren’t met. Prompting the user to adjust their input.
Disabled
A number field can be disabled by setting the isDisabled prop. This can be used to maintain layout continuity and communicate that a field may become available later.
Read only
The isReadOnly prop makes a field’s text content immutable. Unlike isDisabled, the field remains focusable and the contents can still be copied.