Components
Number input
Use: Deployed English, Spanish, TagalogExamples
The v1 and v3 variations of this component are identical, excluding the Currency variation which will be added to v3 at a later date. This component does not exist in the USWDS. Teams should switch to the v3 variation in preparation for global color and typography changes that the v3 variation will accept.
Default
View va-number-input v3 default in Storybook
Currency
View va-number-input with currency in Storybook
Hint text
View va-number-input with hint text v3 in Storybook
Valid range
View va-number-input v3 with valid range in Storybook
Error
View va-number-input v3 error in Storybook
Required
View va-number-input v3 required in Storybook
Internationalization
View va-number-input v3 internationalization in Storybook
Widths
View va-number-input v3 widths in Storybook
Usage
When to use number input
- When a number should be the only accepted value within an input element.
- If you can’t reasonably predict a user’s answer to a prompt and there might be wide variability in users’ answers.
- When users want to be able to paste in a response.
When to consider something else
- When users are choosing from a specific set of options.
- A number is not the only accepted value for the input.
- The number should be a type other than number, ie: telephone numbers
How to use
- Number input always has the type of
number
and provides amin
andmax
attribute to set a range on the component. - Only show error validation messages or stylings after a user has interacted with a particular field.
- Avoid using placeholder text that appears within a input field before a user starts typing. If placeholder text is no longer visible after a user clicks into the field, users will no longer have that text available when they need to review their entries. (People who have cognitive or visual disabilities have additional problems with placeholder text.)
Choosing between variations
- Error. Highlights the text input field where the user has made an error that needs to be corrected.
- Required. Indicates to the user that the text input field is required in order to submit the form.
- With Hint Text. Provides a short hint to the user on what to enter into the field.
- Valid Range. A combination of a max and min value indicating an acceptable number range of what can be entered into the field.
- Internationalization. Demonstrates how this components changes when used with the language toggle.
- With Currency. Indicates to the user the expected input is US currency.
- Widths. Indicates to the user the expected length of text input by sizing the field relative to what is expected.
Native Events
- Native onInput and onBlur events are available on this component. They can be used by adding the event handler to your component and it will then listen to the event and respond accordingly when the event fires.
Code usage
Attributes and Properties
Property | Attribute | Type | Default | Description |
---|---|---|---|---|
currency |
currency |
boolean |
false |
Whether this component will be used to accept a currency value. |
enableAnalytics |
enable-analytics |
boolean |
false |
Emit component-library-analytics events on the blur event. |
error |
error |
string |
The error message to render. | |
hint |
hint |
string |
Optional hint text. | |
inputmode |
inputmode |
"decimal" | "numeric" |
The inputmode attribute. | |
label |
label |
string |
The label for the text input. | |
max |
max |
number | string |
Maximum number value The max attribute specifies the maximum value for an input element. | |
messageAriaDescribedby |
message-aria-describedby |
string |
An optional message that will be read by screen readers when the input is focused. | |
min |
min |
number | string |
Minimum number value The min attribute specifies the minimum value for an input element. | |
name |
name |
string |
The name to pass to the input element. | |
required |
required |
boolean |
false |
Set the input to required and render the (Required) text. |
uswds |
uswds |
boolean |
false |
Whether or not the component will use USWDS v3 styling. |
value |
value |
string |
The value for the input. | |
width |
width |
string |
Displays the input at a specific width. Accepts 2xs (4ex), xs (7ex), sm or small (10ex), md or medium (20ex), lg (30ex), xl (40ex), and 2xl (50ex). |
Events
Name | Description |
---|---|
component-library-analytics |
The event used to track usage of the component. This is emitted when the input is blurred and enableAnalytics is true. |
Accessibility considerations
- Avoid
placeholder
text for accessibility reasons. Most browsers’ default rendering of placeholder text does not provide a high enough contrast ratio. - Avoid breaking numbers with distinct sections (such as phone numbers, Social Security Numbers, or credit card numbers) into separate input fields. For example, use one input for phone number, not three (one for area code, one for local code, and one for number). Each field needs to be labeled for a screen reader and the labels for fields broken into segments are often not meaningful.