Components
Textarea
Use: Deployed English, Spanish USWDS v3Examples - v3
Default
View va-textarea default in Storybook
Required
View va-textarea required in Storybook
Hint text
View va-textarea with hint text in Storybook
With Character count
View va-textarea with character count in Storybook
Forms pattern - Single
View va-textarea forms pattern single in Storybook
Forms pattern - Single error
View va-textarea forms pattern single error in Storybook
Forms pattern - Multiple
View va-textarea forms pattern multiple in Storybook
Forms pattern - Multiple error
View va-textarea forms pattern multiple error in Storybook
Error
View va-textarea error in Storybook
See form error handling for additional guidance.
Examples - v1
Default
View va-textarea v3 default with additional variations in Storybook
Usage
Refer to the U.S. Web Design System for usage guidance
Additional guidance for VA
When to consider something else
- Predictable text. When a short, single line of text is expected and sufficient.
Code usage
Attributes and Properties
Property | Attribute | Type | Default | Description |
---|---|---|---|---|
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. | |
label |
label |
string |
The label for the textarea. | |
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. | |
name |
name |
string |
The name for the input. | |
placeholder |
placeholder |
string |
The placeholder string. | |
required |
required |
boolean |
false |
Set the input to required and render the (Required) text. |
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 of the textarea |
Events
Name | Description |
---|---|
component-library-analytics |
The event used to track usage of the component. This is emitted when the textarea 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
- 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 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. - Only show error validation messages or stylings after a user has interacted with a particular field. Do not interrupt a user while they are entering text into a textarea.