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
Text input allows people to enter any type of text unless otherwise restricted.

Examples

Default

View va-text-input in Storybook

Error

View va-text-input in Storybook

Success

View va-text-input in Storybook

Required

View va-text-input in Storybook

Text input with hint text

This should be used in cases where the needed clarification is long or complex, requiring more than two sentences, multiple paragraphs, or special formatting, such as bullet points or links.

Note that in general we want to avoid this pattern - if a field needs a lot of explanation, it should ideally be moved to its own page with explanation on the page itself. See other options for Hint text

View va-text-input–with-hint-text in Storybook

Usage

When to use text input

  • If you can’t reasonably predict a user’s answer to a prompt and there might be wide variability in users’ answers.
  • When using another type of input will make answering more difficult. For example, birthdays and other known dates are easier to type in than they are to select from a calendar picker.
  • 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.

How to use

  • The length of the text input provides a hint to users as to how much text to write. Do not require users to write paragraphs of text into a single-line input box; use a textarea instead.
  • Text input is among the easiest type of input for desktop users but are more difficult for mobile users. Consider using specific pattern attributes or type="tel" or type="number" to trigger specific mobile keyboards.
  • Required fields are indicated within the label with the text “(*Required)”. All required fields must be indicated. All fields not marked as required are optional.

Errors

  • For all text inputs, the error message is placed between the label and the input.
  • See form error handling for additional guidance.
Error Error message
Error Error message
Error Error message
<div class="usa-input-error">
  <label class="usa-input-error-label" for="text-input-161">Label</label>
  <span class="usa-input-error-message" role="alert" id="text-input-161-error-message">
  <span class="sr-only">Error</span> Error message</span>
  <input type="text" aria-describedby="text-input-161-error-message" id="text-input-161" placeholder="Placeholder" name="Name" maxlength="255" />
</div>

<div class="usa-input-error">
  <label class="usa-input-error-label" for="number-input-155">Please pick a number</label>
  <span class="usa-input-error-message" role="alert" id="number-input-155-error-message"><span class="sr-only">Error</span> Error message</span>
  <input type="number" min="1" max="10" aria-describedby="number-input-155-error-message" id="number-input-155" name="Name" placeholder="Numbers are between 1 and 10" />
</div>

<div class="usa-input-error">
  <label id="textarea-160-label" class="usa-input-error-label" for="textarea-160">Label</label>
  <span class="usa-input-error-message" role="alert" id="textarea-160-error-message">
    <span class="sr-only">Error</span>
    Error message
  </span>
  <textarea class="" aria-describedby="textarea-160-error-message" aria-labelledby="textarea-160-label" id="textarea-160" placeholder="Placeholder" name="Name" maxlength="255"></textarea>
</div>

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
autocomplete autocomplete string What to tell the browser to auto-complete the field with.
enableAnalytics enable-analytics boolean false Emit component-library-analytics events on the blur event.
error error string The error message to render.
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.
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
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.
value value string The value for the input.

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 as 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.
  • 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: Jul 18, 2022