A basic number input component only needs the label property to be displayed. Other props can be used to complement its behavior: placeholder, secondaryLabel, onChange, or the number specific ones.
<NumberInput label="Number input component" placeholder="Write what you want here" secondaryLabel="Free text input" />
The number input component allows setting up the max and min values. However, this is not related to a validation feature but to the component behavior. When setting any of these two properties, it will not be possible to use the component arrows to set a value that is lower than the min prop or a value that is higher than the max prop.
If specific validation is needed, it will need to be handled by the developer. For some details see the Number input validation on change example.
<NumberInput label="Number input component with min and max" placeholder="Enter a value" secondaryLabel="Test the limits with using the arrows" min={20} max={40} />
The number input component does not provide a specific validation logic, but it provides the way to include the developer validation and use the stateMessages property to display any required error message.
This is an example of handling validation when onChange event is triggered.
exportfunctionNumberInputValidation(){ const[validationMessages, setValidationMessages]=useState({}); const max =100; const min =0; const onChange =useCallback((e, newValue)=>{ setValidationMessages({}); if(newValue &&(newValue > max || newValue < min)){ setValidationMessages({ error:['Value must be between 0 and 100'], }); } },[]); return( <NumberInput label="Enter value" secondaryLabel="Min = 0. Max = 100" stateMessages={validationMessages} min={min} max={max} onChange={onChange} /> ); }
The decimalPlaces property allows you to specify how many decimal values must be displayed. By default, no restriction is applied and any value entered by the user will be displayed, however it will be modified when the input loses focus. This will also round the value to the closest digit when entered.
For example, if decimalPlaces is set to 2 and the user enters 5.666 it will convert to 5.67 when the input loses focus.
<NumberInput label="Number input component limited decimals" placeholder="Enter a value" secondaryLabel="Try to add an additional digit" initialValue={5.66} decimalPlaces={2} /> />
When the decimalPlaces property is set, a user may still enter additional digits and the rounding will not occur until after the element loses focus. To warn a user that the value will change, you can add validation logic to display a warning.
The number input enables users to enter or select numeric values within a predetermined range. It includes controls to incrementally increase or decrease the value. Users can also type numeric values directly into the input field.
Helper text (optional): Provides extra context, hints, or helpful information to aid the user. Often used to explain specific requirements for correctly filling out a field.
Numeric value: changes when the user enters a value into the field or uses the two arrows at the end of the input to add and subtract values.
Number input field: the container, consisting of a fill and a stroke, in which the user enters data.
Use help text to provide guidance about what to input and how. Here are some examples of what you might include in help text:
Context to aid the user, such as how the information will be used
Hints for what kind of information goes inside the input field
Formatting examples or requirements
Only use help text for pertinent information. Avoid using help text that simply restates the same information that appears in the label.
Use sentence case for help text. Write the help text as 1-2 short, complete sentences that end with a period. When showing formatting examples, you don't need to end with a period.
Do use help text to provide additional aid or context to the user.
Don't use help text to simply restate the same information that appears in the label.
Don't put placeholder text in the number entry field. Placeholder text strains users' short-term memory because it disappears once a value is entered. It also poses additional burdens for users with visual and cognitive impairments.
Instead, place hints and instructions, including formatting examples and requirements, outside of the field.
Error message text tells a user how to fix the error. In the case of the number input field, errors are often related to something that must be fixed for in-line validation. For example, if the user doesn't fill out a required field that asks for their estimated annual mileage, you can use error text to guide them to a solution: “Enter your estimated annual mileage.”
Use sentence case for error text. Write 1-2 short, complete sentences that end with a period.
Do use error text to guide the user and show them a solution.
Don't write ambiguous error messages or leave users guessing as to how to resolve a problem.
Use an asterisk (*) to indicate required fields. The asterisk precedes the field label. This helps users to easily locate which fields are required by scanning just the left-most character of the label.
In addition to marking required fields with an asterisk, it is recommended to include clear instructions at the top of the form, such as "All fields marked with an asterisk are mandatory," to ensure users understand the meaning of the asterisk.
Do use an asterisk to indicate that a field is required.
Don't use an asterisk to denote anything that is optional.
The number input field appears with no value (default), placeholder text, or a filled input.
Visual
State
Description
No value (default)
Indicates to the user that no value has been entered and there is no placeholder.
Placeholder
Indicates to the user that no value has been entered. The placeholder is grayed out.
Filled input
Indicates to the user that the input is filled with data.
Number input fields also have interactive states for enabled, focus, disabled, error, read-only, and display-only.
State
Description
Enabled
Indicates to the user that the element is enabled for interaction.
Focus
Indicates to the user which UI element in the system is focused.
Disabled
Indicates to the user that the input value can't be changed because of local factors. For example, a checkbox above the input field must be checked to access this input field. The user can take action to enable it by interacting with the page.
Error
Indicates that the user has made a validation error. Error text provides corrective feedback to users.
Read-only
Indicates to the user that the input value can't be changed because of outside factors. For example, lack of write access. The user can take action to enable it by, for example, contacting an administrator.
Display-only
The display-only state is used for two cases:
A UI element is used in display mode.
A UI element is displayed in edit mode, but is never editable.
Users can activate a number input by clicking in the area inside border. When focused, two arrows appear at the end of the input. These controls enable users to incrementally increase or decrease the value.
The number input component derives its accessible name through an aria-label attribute. Changing the text value of the label element also changes the value of the accessible name. The default aria-required='true' attribute toggles to 'false' when the required checkbox is checked in Storybook.
The contrast ratio of textual elements against their background is above 4.5:1 as per WCAG 2.1 AA requirements. Non-textual content that needs to convey meaning (such as icons and keyboard focus visibility) has a contrast ratio of at least 3:1 with its adjacent colors. All content is visible and functional up to and including 400% without requiring scrolling in two dimensions.
This component has been validated to meet the WCAG 2.1 AA accessibility guidelines. However, changes made by the content author can affect accessibility conformance.
When using this component within your application, ensure that labels and instructions are meaningful and concise. Provide supplemental instructions if necessary.
Note: There are deprecated versions of this component. Switch to a version of the docs older than 10.0.x to view their docs.
Make sure to understand the Design System components API surface, and the implications and trade-offs. Learn more in our introduction to the component API.
The number of decimal places to display in the value. If not set, no restriction is applied. When a user enters a value with more decimal places it will round the value. For example, if decimalPlaces is 2 and the user enters 5.666666 it will convert the value to 5.67.
If set to true, displays the component value in plain text. Consider using readonly instead, if possible, because plain text is worse for accessibility than readonly inputs.
Step value for value change. If this prop is passed, component will increase/decrease its value by the specified step on arrow up/down key/button press.
Value of input. Takes precedence over initialValue. If this prop is passed, component works in controlled mode and its value will change only if this prop changes.
You can use HTML input attributes, except any of the ones which are overridden by Jutro. These attributes will be assigned to the HTML input element.
Please note that the most number input specific attributes (step, min and max) are included as part of the component API and might have some Jutro specific logic associated.
Jutro inputs have implemented imperative handlers as a mechanism to provide access to some common native features that might be useful for you. The following features are available:
Set focus to allow you to set the user focus into a specific component
Blur to remove the focus from the component
Scroll to the component so that you can take the user to a specific area of the page.
These features are provided through the ref property, which exposes them as follows:
Although some Jutro components might provide complementary features or a helper function to facilitate the validation process, it is your responsibility as a developer to handle the validation of any user input (using or not using the complementary helpers) and to decide what error messages to show.
Jutro components behave based on the developer implementation.
When are error messages displayed?
Error messages are only displayed when you pass them to the component through the stateMessages property. This property receives an object with the following content:
The component displays every error message provided in the same order as in the array.
When does validation occur?
This is your decision as a developer. As components do not determine when the validation is performed or when the error must be displayed, you need to implement the logic to handle it according to the project requirements, for example while the user is editing the content, when the component loses focus, and on form submission.
New @jutro/components/NumberInput component introduced replacing InputNumberField.
The previous number-related component, InputNumberField was deprecated and moved to the @jutro/legacy package. To view its documentation switch to an older version.
