Textarea

Usage

Overview

TextArea captures multi-line user text: resolution notes, incident summaries, free-text searches that accept line breaks, configuration blobs operators paste, supervisor feedback. It supports labels, helper and error text, optional character counts, and auto-resize within bounds. The mental model is "type freely, but stay within the stated limits". Choose it when line breaks matter or when the expected length can't fit in a single-line field without scrolling.

Reviewer note

Shared with the call taker during dispute review.

When to use

Paragraph-length input, incident or QA notes, free-text search that allows multiple lines, configuration text operators paste in.
Situations where line breaks matter to the operator or to the downstream system.
Read-only display of multi-line system text inside a field-shaped container.

When not to use

Single-line values (names, titles, short codes)—use Input.
Structured data (phone, date, currency)—masked input or pickers fit better.
Rich text with formatting—use a rich-text editor pattern if the product provides one.

Variants

Aspect	Purpose	Emphasis
Auto-resize	Grows with content	Set `minRows` and `maxRows` to prevent runaway height
Fixed rows	Stable layout	Use when alignment with neighbor fields matters
Vertical resize handle	User-controlled height	Only when the layout tolerates variable height
Character counter	Enforces limits	Show when the limit is tight or legally required

Content guidelines

Labels. Sentence case; name the content ("Resolution notes") rather than leaving it at "Notes".
Helper text. Format hints, tone guidance, or privacy notes before errors appear.
Errors. Direct the operator to the fix ("Reduce to 500 characters", not "Invalid").
Placeholder. Example content only; never the sole explanation of requirements.
Localize all strings with formatMessage; some languages need more vertical space—test auto-resize caps with the longest expected translation.

Behavior and states

Focus. Visible focus ring; opt into auto-focus only when it doesn't steal context from more important fields on the page.
Validation. Validate length on blur or submit unless live feedback is a known win. Avoid shouting errors mid-word unless necessary.
Disabled vs. read-only. Match Input semantics—explain the disabled state in helper text when it isn't obvious.
Paste. Large pastes should not freeze the UI; truncate or warn according to product rules.

Best practices

Pair maxLength with a visible counter when operators commonly hit the cap. Surprise failures on submit feel broken.
Choose maxRows so dialogs and drawers still scroll predictably.
Group related long fields with consistent widths so the surface reads as a column of peers.

Don't

Use textarea for log dumps operators shouldn't edit. Use read-only Text or a code viewer.
Hide the character limit until the operator tries to submit.
Force tiny row counts for content that's inherently long.

Accessibility

Label associates with the control's id; aria-describedby references helper and error regions; required and invalid states are exposed; counter updates use polite live regions only when useful. See Accessibility for the full contract.

Input for single-line text.
Label for labelling standards.
Text for read-only display.

Task / Accessibility

Textarea / API and Development

On this page

Textarea

Usage

Overview

Reviewer note

Shared with the call taker during dispute review.

When to use

Paragraph-length input, incident or QA notes, free-text search that allows multiple lines, configuration text operators paste in.
Situations where line breaks matter to the operator or to the downstream system.
Read-only display of multi-line system text inside a field-shaped container.

When not to use

Single-line values (names, titles, short codes)—use Input.
Structured data (phone, date, currency)—masked input or pickers fit better.
Rich text with formatting—use a rich-text editor pattern if the product provides one.

Variants

Aspect	Purpose	Emphasis
Auto-resize	Grows with content	Set `minRows` and `maxRows` to prevent runaway height
Fixed rows	Stable layout	Use when alignment with neighbor fields matters
Vertical resize handle	User-controlled height	Only when the layout tolerates variable height
Character counter	Enforces limits	Show when the limit is tight or legally required

Content guidelines

Labels. Sentence case; name the content ("Resolution notes") rather than leaving it at "Notes".
Helper text. Format hints, tone guidance, or privacy notes before errors appear.
Errors. Direct the operator to the fix ("Reduce to 500 characters", not "Invalid").
Placeholder. Example content only; never the sole explanation of requirements.
Localize all strings with formatMessage; some languages need more vertical space—test auto-resize caps with the longest expected translation.

Behavior and states

Focus. Visible focus ring; opt into auto-focus only when it doesn't steal context from more important fields on the page.
Validation. Validate length on blur or submit unless live feedback is a known win. Avoid shouting errors mid-word unless necessary.
Disabled vs. read-only. Match Input semantics—explain the disabled state in helper text when it isn't obvious.
Paste. Large pastes should not freeze the UI; truncate or warn according to product rules.

Best practices

Pair maxLength with a visible counter when operators commonly hit the cap. Surprise failures on submit feel broken.
Choose maxRows so dialogs and drawers still scroll predictably.
Group related long fields with consistent widths so the surface reads as a column of peers.

Don't

Use textarea for log dumps operators shouldn't edit. Use read-only Text or a code viewer.
Hide the character limit until the operator tries to submit.
Force tiny row counts for content that's inherently long.

Accessibility

Input for single-line text.
Label for labelling standards.
Text for read-only display.

Task / Accessibility

Textarea / API and Development

On this page