Skip to main content
U.S. flag

An official website of the United States government

Dot gov

The .gov means it’s official.
Federal government websites often end in .gov or .mil. Before sharing sensitive information, make sure you’re on a federal government site.


The site is secure.
The https:// ensures that you are connecting to the official website and that any information you provide is encrypted and transmitted securely.


Number input

Use with caution: Available English, Spanish, Tagalog USWDS v3
Number input elements are used for numeric inputs.

Scheduled for Deprecation

This component is planned to be deprecated and it's functionality will be added to Text Input. View the deprecation issue for the current status.



View va-number-input default in Storybook

Hint text

View va-number-input with hint text in Storybook

Valid range

View va-number-input with valid range in Storybook


View va-number-input required in Storybook

Forms pattern single

View va-number-input forms pattern single in Storybook

Forms pattern multiple

View va-number-input forms pattern multiple in Storybook


View va-number-input error in Storybook

Forms pattern single error

View va-number-input forms pattern single error in Storybook


View va-number-input internationalization in Storybook


View va-number-input widths in Storybook


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 a min and max 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.


  • Refer to the specific error examples above.

View form error handling for additional guidance

Hint text

View label hint text for additional guidance

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.
formHeading form-heading string The content of the heading if `useFormsPattern` and `uswds` are true.
formHeadingLevel form-heading-level number 3 The heading level for the heading if `useFormsPattern` and `uswds` are true.
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.
useFormsPattern use-forms-pattern string Enabling this will add a heading and description for integrating into the forms pattern. Accepts `single` or `multiple` to indicate if the form is a single input or will have multiple inputs. `uswds` should be true.
uswds uswds boolean true 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).


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.

Using message-aria-describedby

In HTML, the attribute aria-describedby accepts ids of the elements that describe an object. This is used to establish a relationship between an element and text elsewhere that describes it for screen readers.

However, the Design System uses web components and the shadow DOM, which prevents HTML’s aria-describedby from being able to establish the relationship between elements. Because of that, the message-aria-describedby prop is used in our components instead. Instead of accepting ids, it accepts a message string to read out. This message is placed inside the shadow DOM, hidden visually, but made accessible to screen readers. This allows it to function similarly to aria-describedby and have the descriptive text read out when the element is focused.

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.

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.
Edit this page in GitHub (Permissions required)
Last updated: Jun 14, 2024