Number input

The NumberInput has a default increment step of 1, which is adjustable via the step prop for precise value changes. For larger adjustments, users can hold the Shift key while using the arrow keys to apply a stepMultiplier, a prop that defaults to 2. The parsed numeric value can be accessed through the onNumberChange event handler.

The NumberInput is available in two variants: primary and secondary. The default variant is primary but you can switch to secondary using the variant prop.

When deciding between the primary and secondary variants, take into account the background color where the component will be displayed.

By default, the NumberInput is transparent. You can add borders using the bordered prop.

The NumberInput can be disabled to prevent any user interaction or input.

The NumberInput can be set to a read-only state using the readOnly prop, allowing users to highlight and copy the value without editing it.

By default, a dash ('-') serves as the empty marker. You can customize this marker by using the emptyReadOnlyMarker prop if your application needs a different symbol.

Note: To address browser and screen reader limitations in conveying a read-only state, the NumberInput's role is changed to textbox when set to read-only.

Use the read-only state when users need to view the value for their workflow or current task but are not permitted to edit it, such as due to user permissions.

To maintain a cohesive visual flow, numeric values are left-aligned by default, positioned directly beneath the label and other form field elements. If your specific use case or layout requires a different alignment, you can adjust the NumberInput to be right or center aligned using the textAlign prop.

• Right alignment is often used for numeric values to facilitate easier comparison. However, if number fields are mixed with text fields or do not relate to each other, left alignment may enhance the overall visual flow.
• Center alignment can be used to emphasize a particular value, but it should be applied sparingly and only in exceptional cases to avoid disrupting the visual consistency.

To limit the range of accepted values, you can specify a minimum, maximum, or both using the min and max props.

• Clearly communicate the accepted value range by utilizing the FormField's helper text to guide users.
• Use the FormField error state to alert users when they manually enter a value outside the permitted range, indicating that the input is invalid.
• Use the clamp prop to enforce the value to be within range.

By default, even when minimum and maximum values are specified, they are not strictly enforced, allowing users to type values outside this range. However, by setting the prop clamp to true, the input will automatically adjust to the nearest minimum or maximum value when the input field loses focus.

Note: When using the clamp prop, ensure that the screen reader is updated to announce the clamped value, providing an accessible experience for users relying on assistive technologies.

The NumberInput can display validation states, error, warning, and success, through the validationStatus prop.

• Error state: Use the error state to notify users of a critical issue related to the input. This issue may hinder task completion and typically requires user intervention to resolve.
• Warning state: Use the warning state to caution users about a potential issue. While this issue won't stop users from proceeding with the task, it may lead to errors if not addressed.

The NumberInput component offers the ability to format its value using the format callback prop. This feature is typically used in conjunction with a parse callback, which can be used to determine the valid input format and extract the numerical value of the formatted input.

The format callback is designed to work seamlessly with most formatting libraries, such as Intl.NumberFormat. It is strongly recommended to provide a parse callback alongside format to ensure that valid input is entered and its correct numerical value is derived, maintaining precision and consistency.

Note: If a format callback is provided, it will override the decimalScale prop, allowing you to define custom rules for decimal places directly within your formatting logic.

To make large numbers easier to read, you can use a combination of format and parse callbacks to insert commas and separate thousands.

You can use format to convert the numerical value into its compact notation and parse to convert compact notation back to its numerical value. This is useful when used with charts or other forms of data visualization. The example below supports the following compact notations: The example below supports the following conversion:

• Thousands to K
• Millions to M
• Billions to B
• Trillions to T

You can add a suffix or prefix with a custom format function.

You can support custom input patterns, such as "10x", using a combination of pattern, format and parse callbacks.

Decimals in JavaScript are subject to precision issues. The default format and parse functions use standard JavaScript number handling and may be affected by these limitations. For high-precision decimal support, we recommend providing custom format and parse functions using a library like decimal.js.

• When dealing with currencies such as pounds sterling or U.S. dollars in a retail context, limit the decimal places to two, as these currencies typically require only two decimal places for accuracy. Avoid using three decimal places in such scenarios to maintain consistency and relevance.

When using the default parser and formatter, always use the onNumberChange event to obtain the parsed numeric value and handle precision appropriately in your application logic.

The step prop allows you to define the increment and decrement sizes for value adjustments.

Make sure the step value is suitable for the context. For example, when users are inputting a "Number of people," increments of 0.5 may cause confusion. If unsure, maintain the step at 1 to ensure clarity and simplicity.

You can add a custom Button at the end of the NumberInput using the endAdornment prop. This allows for custom interactivity within the input field.

When using endAdornment buttons for tasks such as reset or synchronization, it is essential to provide immediate feedback to users, especially those using screen readers. Implementing an aria-live region ensures that screen readers announce dynamic content changes, keeping users informed about actions such as resetting or synchronizing the input field. This improves user understanding and interaction with the application.

Reset adornment:

Use a reset button to return the NumberInput to its default value.

Synchronize adornment:

Synchronize the NumberInput with a live value from a constantly changing source, such as ticking stock values. The NumberInput's value does not automatically update with changes in the live value. In this scenario, the synchronize button appears when the displayed value and live value differ.

Custom buttons:

Customize the positioning and appearance of NumberInput's arrow buttons to align with specific product requirements or constraints.

The NumberInput has a default increment step of 1, which is adjustable via the step prop for precise value changes. For larger adjustments, users can hold the Shift key while using the arrow keys to apply a stepMultiplier, a prop that defaults to 2. The parsed numeric value can be accessed through the onNumberChange event handler.

The NumberInput is available in two variants: primary and secondary. The default variant is primary but you can switch to secondary using the variant prop.

When deciding between the primary and secondary variants, take into account the background color where the component will be displayed.

By default, the NumberInput is transparent. You can add borders using the bordered prop.

The NumberInput can be disabled to prevent any user interaction or input.

The NumberInput can be set to a read-only state using the readOnly prop, allowing users to highlight and copy the value without editing it.

By default, a dash ('-') serves as the empty marker. You can customize this marker by using the emptyReadOnlyMarker prop if your application needs a different symbol.

Note: To address browser and screen reader limitations in conveying a read-only state, the NumberInput's role is changed to textbox when set to read-only.

Use the read-only state when users need to view the value for their workflow or current task but are not permitted to edit it, such as due to user permissions.

To maintain a cohesive visual flow, numeric values are left-aligned by default, positioned directly beneath the label and other form field elements. If your specific use case or layout requires a different alignment, you can adjust the NumberInput to be right or center aligned using the textAlign prop.

• Right alignment is often used for numeric values to facilitate easier comparison. However, if number fields are mixed with text fields or do not relate to each other, left alignment may enhance the overall visual flow.
• Center alignment can be used to emphasize a particular value, but it should be applied sparingly and only in exceptional cases to avoid disrupting the visual consistency.

To limit the range of accepted values, you can specify a minimum, maximum, or both using the min and max props.

• Clearly communicate the accepted value range by utilizing the FormField's helper text to guide users.
• Use the FormField error state to alert users when they manually enter a value outside the permitted range, indicating that the input is invalid.
• Use the clamp prop to enforce the value to be within range.

By default, even when minimum and maximum values are specified, they are not strictly enforced, allowing users to type values outside this range. However, by setting the prop clamp to true, the input will automatically adjust to the nearest minimum or maximum value when the input field loses focus.

Note: When using the clamp prop, ensure that the screen reader is updated to announce the clamped value, providing an accessible experience for users relying on assistive technologies.

The NumberInput can display validation states, error, warning, and success, through the validationStatus prop.

• Error state: Use the error state to notify users of a critical issue related to the input. This issue may hinder task completion and typically requires user intervention to resolve.
• Warning state: Use the warning state to caution users about a potential issue. While this issue won't stop users from proceeding with the task, it may lead to errors if not addressed.

The NumberInput component offers the ability to format its value using the format callback prop. This feature is typically used in conjunction with a parse callback, which can be used to determine the valid input format and extract the numerical value of the formatted input.

The format callback is designed to work seamlessly with most formatting libraries, such as Intl.NumberFormat. It is strongly recommended to provide a parse callback alongside format to ensure that valid input is entered and its correct numerical value is derived, maintaining precision and consistency.

Note: If a format callback is provided, it will override the decimalScale prop, allowing you to define custom rules for decimal places directly within your formatting logic.

To make large numbers easier to read, you can use a combination of format and parse callbacks to insert commas and separate thousands.

You can use format to convert the numerical value into its compact notation and parse to convert compact notation back to its numerical value. This is useful when used with charts or other forms of data visualization. The example below supports the following compact notations: The example below supports the following conversion:

• Thousands to K
• Millions to M
• Billions to B
• Trillions to T

You can add a suffix or prefix with a custom format function.

You can support custom input patterns, such as "10x", using a combination of pattern, format and parse callbacks.

Decimals in JavaScript are subject to precision issues. The default format and parse functions use standard JavaScript number handling and may be affected by these limitations. For high-precision decimal support, we recommend providing custom format and parse functions using a library like decimal.js.

• When dealing with currencies such as pounds sterling or U.S. dollars in a retail context, limit the decimal places to two, as these currencies typically require only two decimal places for accuracy. Avoid using three decimal places in such scenarios to maintain consistency and relevance.

When using the default parser and formatter, always use the onNumberChange event to obtain the parsed numeric value and handle precision appropriately in your application logic.

The step prop allows you to define the increment and decrement sizes for value adjustments.

Make sure the step value is suitable for the context. For example, when users are inputting a "Number of people," increments of 0.5 may cause confusion. If unsure, maintain the step at 1 to ensure clarity and simplicity.

You can add a custom Button at the end of the NumberInput using the endAdornment prop. This allows for custom interactivity within the input field.

When using endAdornment buttons for tasks such as reset or synchronization, it is essential to provide immediate feedback to users, especially those using screen readers. Implementing an aria-live region ensures that screen readers announce dynamic content changes, keeping users informed about actions such as resetting or synchronizing the input field. This improves user understanding and interaction with the application.

Reset adornment:

Use a reset button to return the NumberInput to its default value.

Synchronize adornment:

Synchronize the NumberInput with a live value from a constantly changing source, such as ticking stock values. The NumberInput's value does not automatically update with changes in the live value. In this scenario, the synchronize button appears when the displayed value and live value differ.

Custom buttons:

Customize the positioning and appearance of NumberInput's arrow buttons to align with specific product requirements or constraints.

The NumberInput has a default increment step of 1, which is adjustable via the step prop for precise value changes. For larger adjustments, users can hold the Shift key while using the arrow keys to apply a stepMultiplier, a prop that defaults to 2. The parsed numeric value can be accessed through the onNumberChange event handler.

The NumberInput is available in two variants: primary and secondary. The default variant is primary but you can switch to secondary using the variant prop.

When deciding between the primary and secondary variants, take into account the background color where the component will be displayed.

By default, the NumberInput is transparent. You can add borders using the bordered prop.

The NumberInput can be disabled to prevent any user interaction or input.

The NumberInput can be set to a read-only state using the readOnly prop, allowing users to highlight and copy the value without editing it.

By default, a dash ('-') serves as the empty marker. You can customize this marker by using the emptyReadOnlyMarker prop if your application needs a different symbol.

Note: To address browser and screen reader limitations in conveying a read-only state, the NumberInput's role is changed to textbox when set to read-only.

Use the read-only state when users need to view the value for their workflow or current task but are not permitted to edit it, such as due to user permissions.

To maintain a cohesive visual flow, numeric values are left-aligned by default, positioned directly beneath the label and other form field elements. If your specific use case or layout requires a different alignment, you can adjust the NumberInput to be right or center aligned using the textAlign prop.

• Right alignment is often used for numeric values to facilitate easier comparison. However, if number fields are mixed with text fields or do not relate to each other, left alignment may enhance the overall visual flow.
• Center alignment can be used to emphasize a particular value, but it should be applied sparingly and only in exceptional cases to avoid disrupting the visual consistency.

To limit the range of accepted values, you can specify a minimum, maximum, or both using the min and max props.

• Clearly communicate the accepted value range by utilizing the FormField's helper text to guide users.
• Use the FormField error state to alert users when they manually enter a value outside the permitted range, indicating that the input is invalid.
• Use the clamp prop to enforce the value to be within range.

By default, even when minimum and maximum values are specified, they are not strictly enforced, allowing users to type values outside this range. However, by setting the prop clamp to true, the input will automatically adjust to the nearest minimum or maximum value when the input field loses focus.

Note: When using the clamp prop, ensure that the screen reader is updated to announce the clamped value, providing an accessible experience for users relying on assistive technologies.

The NumberInput can display validation states, error, warning, and success, through the validationStatus prop.

• Error state: Use the error state to notify users of a critical issue related to the input. This issue may hinder task completion and typically requires user intervention to resolve.
• Warning state: Use the warning state to caution users about a potential issue. While this issue won't stop users from proceeding with the task, it may lead to errors if not addressed.

The NumberInput component offers the ability to format its value using the format callback prop. This feature is typically used in conjunction with a parse callback, which can be used to determine the valid input format and extract the numerical value of the formatted input.

The format callback is designed to work seamlessly with most formatting libraries, such as Intl.NumberFormat. It is strongly recommended to provide a parse callback alongside format to ensure that valid input is entered and its correct numerical value is derived, maintaining precision and consistency.

Note: If a format callback is provided, it will override the decimalScale prop, allowing you to define custom rules for decimal places directly within your formatting logic.

To make large numbers easier to read, you can use a combination of format and parse callbacks to insert commas and separate thousands.

You can use format to convert the numerical value into its compact notation and parse to convert compact notation back to its numerical value. This is useful when used with charts or other forms of data visualization. The example below supports the following compact notations: The example below supports the following conversion:

• Thousands to K
• Millions to M
• Billions to B
• Trillions to T

You can add a suffix or prefix with a custom format function.

You can support custom input patterns, such as "10x", using a combination of pattern, format and parse callbacks.

Decimals in JavaScript are subject to precision issues. The default format and parse functions use standard JavaScript number handling and may be affected by these limitations. For high-precision decimal support, we recommend providing custom format and parse functions using a library like decimal.js.

• When dealing with currencies such as pounds sterling or U.S. dollars in a retail context, limit the decimal places to two, as these currencies typically require only two decimal places for accuracy. Avoid using three decimal places in such scenarios to maintain consistency and relevance.

When using the default parser and formatter, always use the onNumberChange event to obtain the parsed numeric value and handle precision appropriately in your application logic.

The step prop allows you to define the increment and decrement sizes for value adjustments.

Make sure the step value is suitable for the context. For example, when users are inputting a "Number of people," increments of 0.5 may cause confusion. If unsure, maintain the step at 1 to ensure clarity and simplicity.

You can add a custom Button at the end of the NumberInput using the endAdornment prop. This allows for custom interactivity within the input field.

When using endAdornment buttons for tasks such as reset or synchronization, it is essential to provide immediate feedback to users, especially those using screen readers. Implementing an aria-live region ensures that screen readers announce dynamic content changes, keeping users informed about actions such as resetting or synchronizing the input field. This improves user understanding and interaction with the application.

Reset adornment:

Use a reset button to return the NumberInput to its default value.

Synchronize adornment:

Synchronize the NumberInput with a live value from a constantly changing source, such as ticking stock values. The NumberInput's value does not automatically update with changes in the live value. In this scenario, the synchronize button appears when the displayed value and live value differ.

Custom buttons:

Customize the positioning and appearance of NumberInput's arrow buttons to align with specific product requirements or constraints.