Components

Textarea

use: best-practice English, Spanish

USWDS v3

Textarea allows people to enter any type of text.

Examples

Usage

Additional guidance for VA

When to consider something else

Predictable text. When a short, single line of text is expected and sufficient.

Errors

Refer to the specific error examples above.

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

formHeadingLevel form-heading-level number 3

The heading level for the heading if useFormsPattern is true.

headerAriaDescribedby header-aria-describedby string

An optional message that will be read by screen readers when the header is focused. The label-header-level prop must be set for this to be active.

hint hint string

Optional hint text.

label label string

The label for the textarea.

labelHeaderLevel label-header-level string

Insert a header with defined level inside the label (legend)

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.

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

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

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.

Privacy guidance

An open text field has a high risk for users to enter Personally Identifiable Information (PII) or Protected Health Information (PHI).

Responses provided in open text fields should never be tracked in analytics
If the responses are utilized in elements on follow-on or related pages—such as an H1—ensure that information isn’t tracked in analytics or passed in URLs

Learn more about PII/PHI on the VA Platform website

Edit this page in GitHub (Permissions required)

Last updated: Jul 02, 2025

Textarea

Examples

Default

Required

Hint text

With Character count

Forms pattern - Single

Forms pattern - Single error

Forms pattern - Multiple

Forms pattern - Multiple error

Error