Components
Text input
Use: Deployed English, Spanish, Tagalog USWDS v3Examples - v3
Default
View va-text-input in Storybook
Required
View va-text-input Required in Storybook
Pattern
View va-text-input Pattern in Storybook
Autocomplete
View va-text-input Autocomplete in Storybook
Hint Text
View va-text-input with Hint text in Storybook
Also refer to the overall form guidance for hint text examples and usage.
Inline Hint Text
View va-text-input with inline Hint text in Storybook
With Additional Info
View va-text-input with Additional info in Storybook
With Character count
View va-text-input with character count in Storybook
Forms pattern - Single
View va-text-input forms pattern single in Storybook
Forms pattern - Single error
View va-text-input forms pattern single error in Storybook
Forms pattern - Multiple
View va-text-input forms pattern multiple 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
Internationalization
View va-text-input Internationalization in Storybook
Widths
View va-text-input widths in Storybook
Examples - v1
Default
View va-text-input v1 default and additional variations in Storybook
Usage
Refer to the U.S. Web Design System for usage guidance
Choosing between variations
- 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.
- 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.
- With Hint Text. Provides a short hint to the user on what to enter into the field.
- With 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.
- With Additional Info. Depicts how to use the additional info component within a va-text-input.
- With 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.
- 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.
- 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 |
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). |
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 id
s 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 id
s, 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
Refer to the U.S. Web Design System for accessibility guidance
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. - When using placeholder text, provide screen reader accessible text. When using the placeholder prop, which is used automatically by the Max length variation (v1 only), 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.