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.

Https

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.

Components

Text input

Use: Deployed English, Spanish, Tagalog USWDS v3
Text input allows people to enter any type of text unless otherwise restricted.

Examples - v1

Default

View va-text-input in Storybook

Error

View va-text-input Error in Storybook

See form error handling for additional guidance.

Success

View va-text-input Success in Storybook

Required

View va-text-input Required in Storybook

Internationalization

View va-text-input Internationalization in Storybook

Max length

View va-text-input Max length in Storybook

Range

View va-text-input Range in Storybook

Pattern

View va-text-input Pattern in Storybook

With Hint Text

View va-text-input with Hint text in Storybook

Also refer to the overall form guidance for hint text examples and usage.

With Additional Info

View va-text-input with Additional info in Storybook

Widths

View va-text-input widths in Storybook

Examples - v3

Default

View va-text-input v3 default in Storybook

Usage

Refer to the U.S. Web Design System for usage guidance

Behavior

  • Max length variation. The Max length variation adds placeholder text inside the text-input. Once the user starts typing, this placeholder text disappears. Once the user has entered the same number of characters as the max length, text appears below the field in the following format: (Max. NN characters). At that point no additional text can be entered into the text-input. If the user removes one or more characters and thus goes below the max limit the text beneath the field is removed.

Choosing between variations

  • Error. Highlights the text input field where the user has made an error that needs to be corrected.
  • Success. Indicates to the user in realtime that an error has been cleared and the text entry is now valid. NOTE: This isn’t typically used currently.
  • Required. Indicates to the user that the text input field is required in order to submit the form.
  • Internationalization. Demonstrates how this components changes when used with the language toggle.
  • Max Length. Indicates to the user when a maximum number of characters has been entered into the text input field.
  • Min Length. Indicates to the user when a minimum number of characters must be entered into a field.
  • Range. A combination of the above max and min length parameters indicating an acceptable range of characters to be entered into the field.
  • Pattern. Allows for a pattern of characters to be required for a the text input entry to be valid.
  • Autocomplete. Provides type-ahead functionality.
  • With Hint Text. Provides a short hint to the user on what to enter into the field.
  • With Additional Info. Depicts how to use the additional info component within a va-text-input.
  • Widths. Indicates to the user the expected length of text input by sizing the field relative to what is expected.

Code usage

Attributes and Properties

Property Attribute Type Default Description
autocomplete autocomplete string Allows the browser to automatically complete the input.
charcount charcount boolean false Whether the component should show a character count message. Has no effect without uswds and maxlength being set.
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" | "email" | "numeric" | "search" | "tel" | "text" | "url" The inputmode attribute.
invalid invalid boolean false Whether or not `aria-invalid` will be set on the inner input. Useful when composing the component into something larger, like a date component.
label label string The label for the text input.
maxlength maxlength number The maximum number of characters allowed in the input. Negative and zero values will be ignored.
messageAriaDescribedby message-aria-describedby string An optional message that will be read by screen readers when the input is focused.
minlength minlength number The minimum number of characters allowed in the input.
name name string The name to pass to the input element.
pattern pattern string The regular expression that the input element's value is checked against on submission
reflectInputError reflect-input-error boolean false Whether or not to add usa-input--error as class if error message is outside of component
required required boolean false Set the input to required and render the (Required) text.
success success boolean false Adds styling based on status value
type type "email" | "number" | "search" | "tel" | "text" | "url" 'text' The type attribute.
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 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.

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

Refer to the U.S. Web Design System for accessibility guidance

Additional accessibility considerations for VA

  • Avoid placeholder text. Excluding our max characters variation, avoid using placeholder text. Most browsers’ default rendering of placeholder text does not provide a high enough contrast ratio. Also, placeholder text is no longer visible once a user clicks into the field. Thus 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.
  • When using placeholder text, provide screen reader accessible text. When using the placeholder prop, which is used automatically by the Max length variation, additional work is required to make the component accessible. Screen readers such as JAWS and NVDA don’t read placeholder text. Placeholder text is a visual addition only. Thus when using placeholder text to provide important information visually you must also convey this information to screen reader users as well. To do this, add screen read only text within a <span> using the .sr-only CSS class and place the span and text where you would like it to be read out, typically after the field label.
Edit this page in GitHub (Permissions required)
Last updated: Feb 27, 2024