Required. Indicates to the user that the text input field is required in order to submit the form.
Pattern. Allows for a pattern of characters to be required for the text input entry to be valid.
Valid range. Allows for a range of numeric values to be required for the text input entry to be valid.
Autocomplete. Specifies what if any permission the user agent has to provide automated assistance in filling out form field values, as well as guidance to the browser as to the type of information expected in the field.
Hint Text. Provides a short hint to the user on what to enter into the field.
Inline Hint Text. Provides a very short hint to the user within the label on what to enter into the field. Hint text is preferred to inline hint text.
Additional Info. Depicts how to use the additional info component within a va-text-input.
Character count. Implements the USWDS Character count functionality which displays the character count below the text input. However, our implementation differs from USWDS in that it does not allow for entering more text after the maxlength.
Currency. Indicates that the input accepts a dollar amount.
Forms pattern - Single. This variation can be used to support the One thing per page content principle where we gather one decision, question, or piece of information on the page.
Forms pattern - Single error. Shows the error state for the single form field pattern.
Forms pattern - Multiple . This variation also can be used to support the One thing per page content principle where we gather one decision, question, or piece of information on the page.
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.
Internationalization. Demonstrates how this components changes when used with the language toggle.
Prefix and Suffix. Allows an icon or text to be set as an input prefix and/or suffix. See USWDS Input Prefix and Suffix for additional guidance.
Widths. Indicates to the user the expected length of text input by sizing the field relative to what is expected.

Errors

Refer to the specific error examples above.

Hint text

Refer to the hint text example above.

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 maxlength being set.

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` is true.

formHeadingLevel form-heading-level number 3 The heading level for the heading if `useFormsPattern`is true.

hint hint string Optional hint text.

inputIconPrefix input-icon-prefix string This property displays a prefix that accepts a string which represents icon name.

inputIconSuffix input-icon-suffix string A string that represents the name of an icon passed to va-icon, which will be applied as a suffix to the input.

inputPrefix input-prefix string Displays a fixed prefix string at the start of the input field.

inputSuffix input-suffix string Displays a fixed suffix string at the end of the input field.

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.

max max number | string The max attribute specifies the maximum value for an input element if the inputmode is numeric.

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.

min min number | string The min attribute specifies the minimum value for an input element if the inputmode is numeric.

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.

showInputError show-input-error boolean true When `false`, hides the error message from view, but not from the screen reader. Should only be used if error is being displayed elsewhere. Must use kebab-case on this attribute for it to work properly.

step step string The step attribute is a number, or the string 'any', that specifies the granularity of the value. For example: `` enables float/decimal values to be valid and increment by one-tenth.
Defaults to 1 for every field type except for time and datetime-local which default to 60 (seconds). View more documentation on [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/step)

success success boolean false Adds styling based on status value

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.

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.

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

Additional accessibility considerations for VA

Avoid placeholder text. Excluding our max characters variation (v1), 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.

Text input

Examples

Default

Required

Pattern

Valid Range

Autocomplete

Hint Text

Inline Hint Text

Additional Info

Character count

Currency

Forms pattern - Single

Forms pattern - Single error

Forms pattern - Multiple

Error

Success

Internationalization

Prefix (Icon)

Suffix (Text)

Prefix and Suffix

Widths

Usage

Additional guidance for VA

Choosing between variations