Skip to main content
U.S. flag

An official website of the United States government

Dot gov

The .gov means it’s official.
Federal government websites often end in .gov or .mil. Before sharing sensitive information, make sure you’re on a federal government site.

Https

The site is secure.
The https:// ensures that you are connecting to the official website and that any information you provide is encrypted and transmitted securely.

Components

Textarea

Use: Deployed English, Spanish USWDS v3
Textarea allows people to enter any type of text.

Examples - v1

Default

View va-textarea in Storybook

Error

View va-textarea error in Storybook

See form error handling for additional guidance.

Max length

View va-textarea max length in Storybook

Required

View va-textarea required in Storybook

Hint text

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

Examples - v3

Default

View va-textarea v3 default with additional variations in Storybook

Usage

Refer to the U.S. Web Design System for usage guidance

When to use textarea

Additional guidance for VA

When to consider something else

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

Behavior

  • Max length variation. The Max length variation adds placeholder text inside the textarea. 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 textarea. If the user removes one or more characters and thus goes below the max limit the text beneath the field is removed.

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.
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.
uswds uswds boolean false 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, 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 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.
Edit this page in GitHub (Permissions required)
Last updated: Sep 18, 2023