Textarea

A textarea takes text over several lines, such as a description, a message, or feedback. It is a bare box; wrap it in a Field to give it a label, help text, and errors.

Stable

Figma

Overview

Usage

API

Accessibility

<tk-field label="Description" helper="A couple of sentences about what makes it special">
  <tk-textarea name="description" rows="4" limit="200"></tk-textarea>
</tk-field>

Anatomy

Part	What it is
`tk-textarea`	the element; one Tab stop
`textarea` part	the native `<textarea>`, with its border and resize grip
counter	the character count under the box, shown when `limit` is set

The label, help text, and error message come from a Field. There are no affixes and no size.

Height

<tk-textarea aria-label="Short note" rows="2"></tk-textarea>
<tk-textarea aria-label="Cover letter" rows="8"></tk-textarea>

rows sets the starting height (default 5). Match it to the expected answer: a two-sentence note doesn't need eight rows. The box is never shorter than 2 rows.
People can drag the corner to make it taller, never wider. The width follows your layout.
Longer text scrolls inside the box.

States

<tk-textarea aria-label="Shipping notes" readonly value="Leave at the front desk"></tk-textarea>
<tk-textarea aria-label="Internal notes" disabled value="Locked after review"></tk-textarea>

<tk-field label="Reason for return" required error="Enter a reason for the return">
  <tk-textarea name="reason" rows="3"></tk-textarea>
</tk-field>

The box works like an Input: no change on hover, and on focus its border takes the focus color and grows thicker inward.

readonly: people can focus, select, and copy the text, but not edit it.
disabled: the box can't be focused, edited, or resized, and it's left out of the form. Prefer readonly.
Error: set error on the Field. The border turns red and the message shows under the box.
Required: set required on the Field. Without a Field, set it on the textarea.

Enter adds a new line; it never submits the form. Submit with a button.

Character limit

<tk-field label="Bio">
  <tk-textarea name="bio" rows="3" limit="40" value="Product designer in Lisbon. Loves maps, trains, and good coffee."></tk-textarea>
</tk-field>

limit shows a counter under the box: "You can enter up to 200 characters", then "15 characters remaining", and over the limit, in red, "12 characters too many".
Typing and pasting are never blocked. People can paste a full answer and cut it down.
The red counter is the only signal. It doesn't mark the field invalid or stop the form from submitting. Check the length when the form is submitted, and set error on the Field if it's too long.
Add a limit only when there is a real one, such as a database or legal cap.
maxlength cuts off typing and pasting at the limit. Use limit for prose, and never set both.

When to use

Use a textarea for free text longer than one line. Short or structured answers, such as a name, a phone number, or an email, go in an Input.
Before adding a bigger box, check the question. A hard open question often works better as a few simpler ones with options.
It has no formatting. There is no toolbar, bold, or links.

Content

Label, help text, and error rules are the same as for Input. One more:

Put the prompt in the help text, not the placeholder. A big empty box invites a placeholder, but it disappears on the first keystroke.

Do / Don't

✅ Do	❌ Don't
Set `rows` to the expected answer	Use one height for a note and a cover letter
Use `limit` for prose	Use `maxlength`, which cuts off pasted text
Check the length when the form is submitted	Treat the red counter as validation
Put the prompt in the Field's help text	Put instructions in the placeholder
Split a vague question into simpler ones	Make the box bigger instead

Field: the label, help text, and error around a textarea.
Input: text entry on one line.

API

Attributes

Attribute	Type	Default	What it does
`value`	string	`''`	the text; submits under `name`, line breaks included
`name`	string	—	the form field name
`rows`	number	`5`	the starting height in lines; at least 2
`limit`	number	—	shows the character counter; never blocks typing
`maxlength`	number	—	the browser cuts off text past this length; don't combine with `limit`
`placeholder`	string	—	hint text shown while empty; avoid it
`autocomplete`	string	—	the autofill purpose; set it on personal data
`inputmode`	string	—	the on-screen keyboard
`required`	boolean	`false`	the browser blocks submitting while empty; no visible mark
`readonly`	boolean	`false`	focusable and copyable, not editable
`disabled`	boolean	`false`	not focusable, not editable, left out of the form

Events

No custom events. Listen for input on every keystroke and change when the value is committed; read the value property. Resetting the form restores the first value without firing change.

Methods

focus(): moves focus into the textarea.

CSS

::part(textarea): the native <textarea>.

Tokens

The box uses the Input tokens for every state. Padding is space-8 top and bottom and space-10 at the sides; corners are radius-8; the text is Body Small (14/20). The counter is text/secondary, text/error over the limit. Values per theme: Color.

Accessibility

Built in:

A native <textarea>: Tab reaches it, and selection, autofill, and resizing work.
A composing Field names it, links the help text and error, and marks it invalid on error.
The counter is read to screen readers after people pause typing, never on every key.

Your part:

Give every textarea a name: a Field label, or aria-label.
Check the length yourself when the form is submitted.

Key	Action
`Tab`	moves focus to the textarea; skips it when `disabled`
`Enter`	adds a new line

Contrast limits

The textarea shares the Input's limits: see Input contrast limits.

Anatomy

Height

States

Character limit

When to use

Content

Do / Don't

Related

API

Attributes

Events

Methods

CSS

Tokens

Accessibility

Contrast limits