Textarea

Material Design 3 multi-line text input with auto-resize and character counter. Not intended for rich text or single-line inputs; use ds-text-field for single-line scenarios.

Basic Usage

Use textareas for multi-line input in forms and dialogs. This is the recommended baseline because it uses native <textarea> semantics and supports auto-resize. 

<ds-textarea label="Message" rows="3"></ds-textarea>

Variants

Choose filled or outlined to match layout density and emphasis.

Filled (Default)

Default variant with filled background.

  • Use when: The textarea sits on a flat or neutral surface.
  • Avoid when: The textarea must stand out on an elevated or tonal surface. 
<ds-textarea label="Message" helper-text="Enter your message" rows="3"></ds-textarea>

Outlined

Outlined variant with visible border.

  • Use when: Textarea appears on elevated or tonal surfaces.
  • Avoid when: The filled variant already meets visual hierarchy requirements. 
<ds-textarea variant="outlined" label="Message" helper-text="Enter your message" rows="3"></ds-textarea>

States

Show filled, error, and disabled states clearly.

With Value

Error State

Disabled

<ds-textarea label="Feedback" error error-text="This field is required" helper-text="Please provide your feedback" rows="3"></ds-textarea>

With Helper Text

Provide guidance or validation hints below the input.

<ds-textarea label="Notes" helper-text="Add context for your request" rows="3"></ds-textarea>

Character Counter

Show the remaining character count with a maximum length.

With Maxlength

Outlined with Counter

<ds-textarea label="Bio" maxlength="200" rows="4"></ds-textarea>

Auto-resize

Grow the textarea to match content length.

<ds-textarea label="Notes" helper-text="The textarea will grow as you type" auto-resize rows="2"></ds-textarea>

Interactive Example

Listen for input to update live feedback.

<ds-textarea id="interactive-textarea" label="Your Message" maxlength="300" auto-resize rows="4"></ds-textarea>
<div id="output" class="status-box"></div>

API

Attributes

Attribute Type Default Description
name string "" Form field name. The current text is submitted under it; without a name the field is left out.
required boolean false Whether text must be entered. Blocks the enclosing form's submission until satisfied.
variant string "filled" Visual style: "filled" or "outlined".
label string "" Floating label text.
value string "" Current textarea value.
placeholder string "" Placeholder text (when no label).
helper-text string "" Helper text below textarea.
error boolean false Whether textarea is in error state.
error-text string "" Error message shown when error is true.
disabled boolean false Whether textarea is disabled.
maxlength number null Maximum character count (shows counter).
rows number 3 Initial number of visible rows.
auto-resize boolean true Whether textarea auto-resizes with content.

Forms

Submits its text, "" when empty, like a native <textarea>. required and maxlength block submission. It resets with its form, and a disabled <fieldset> disables it. form, validity, validationMessage, checkValidity() and reportValidity() behave as on a native control.

Events

Event Detail Description
ds-textarea:input { value: string } Fired when the textarea value changes.
ds-textarea:blur { value: string } Fired when the textarea loses focus.

CSS Parts

Part Description
textarea Native textarea element.
label Floating label.
supporting-text Helper or error text.
character-counter Character counter label.

CSS Custom Properties

Property Description
--ds-textarea-width Controls the textarea width (default: 100%).

Accessibility

Keyboard Map

Key Context Expected Result
Tab Textarea not focused Moves focus to the textarea.
Shift+Tab Textarea focused Moves focus to previous element.
Any printable key Textarea focused Appends to textarea content.

Semantics

  • Uses native <textarea> element semantics.
  • Label is associated with the textarea content.
  • Helper text and error messages are announced by screen readers.

Usage Guidelines

  • When to use: Multi-line prose, notes, or descriptions that may exceed a single line.
  • When not to use: Short structured input like names or email addresses; use ds-text-field.
  • Composition: Use max-length with the character counter to communicate limits to the user.
  • Common mistakes: Using a textarea for short structured fields, omitting labels, and not setting a max length.