Components

Text input

Use: Deployed English, Spanish, Tagalog

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 Error in Storybook

See form error handling for additional guidance.

Hint text

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

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.

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.
- Note: When using this variation please note the accessibility considerations that you must take into account.

Code usage

Attributes and Properties

Property	Attribute	Type	Default	Description
`autocomplete`	`autocomplete`	`string`		Allows the browser to automatically complete the input.
`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" \| "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.
`uswds`	`uswds`	`boolean`	`false`	Whether or not the component will use USWDS v3 styling.
`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.

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. 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.
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.