VERIFICATION-0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF
Describe what changed and why. Plain text, up to 500 characters.Textarea
<forma-textarea>
Multi-line native text entry with a visible label and description in the .forma-field structure; the browser owns resizing and form participation.
- Authoring tag
<forma-textarea>- Category
- Form inputs
- Behavior owner
- Native HTML
- Canonical source
patterns/textarea.html
Purpose
A textarea collects free-form text that may run to several sentences or lines. It uses the shared .forma-field structure documented on Text field around a native textarea, so typing, line breaks, spell checking, the resize handle, maxlength and form submission all come from the browser. Forma sets the border, padding, full-width sizing and 44px minimum height.
Use when
- The answer is prose: a change summary, a reason, a note or a message.
- Line breaks are part of the value.
- The expected length is unknown or longer than one line of a Text field.
Avoid when
- The value is a single line such as a name or title: use Text field.
- The user is writing a prompt or message in a conversational interface with send and attachment actions: use Composer.
- The content is structured (a list of items, key/value pairs): give each item its own control instead of asking users to format text.
Behavior to know
- Full width of the field column; height comes from the
rowsattribute. - The browser's resize handle stays available, and
max-inline-size: 100%stops it from pushing past the container. - Character limits are native
maxlength; any live remaining-characters count is application behavior.
Basic example
The smallest correct markup: the canonical pattern from patterns/textarea.html inside its public tag. Copy this first, then adapt labels, names and state.
Minimal textarea
Rendered from the canonical pattern file.
<forma-textarea class="forma-component-tag">
<div class="forma-field">
<label class="forma-field__label" for="textarea-summary">Change summary</label>
<span class="forma-field__description" id="textarea-summary-description">Describe what changed and why. Plain text, up to 500 characters.</span>
<textarea id="textarea-summary" name="summary" rows="4" maxlength="500" aria-describedby="textarea-summary-description"></textarea>
</div>
</forma-textarea>
Click or tap the code once to select all of it, then copy.
Examples
Required rejection reason
A reviewer must explain a rejection. The field is required and the error appears after an empty submit, linked through aria-describedby alongside the guidance.
<forma-textarea class="forma-component-tag">
<div class="forma-field">
<label class="forma-field__label" for="textarea-rejection-reason">Reason for rejecting this change (required)</label>
<span class="forma-field__description" id="textarea-rejection-reason-description">The author sees this text. Say what must change before you can approve.</span>
<textarea id="textarea-rejection-reason" name="rejection-reason" rows="5" required aria-invalid="true" aria-describedby="textarea-rejection-reason-description textarea-rejection-reason-error"></textarea>
<p class="forma-validation-message" id="textarea-rejection-reason-error">
<span class="forma-validation-message__mark" aria-hidden="true">!</span>
Enter a reason so the author knows what to fix.
</p>
</div>
</forma-textarea>
Click or tap the code once to select all of it, then copy.
Read-only incident note
A note from a closed incident. readonly keeps the text focusable, selectable and submitted while preventing edits; the description explains why it is locked.
<forma-textarea class="forma-component-tag">
<div class="forma-field">
<label class="forma-field__label" for="textarea-incident-note">Resolution note</label>
<span class="forma-field__description" id="textarea-incident-note-description">Locked because the incident is closed. Reopen the incident to edit.</span>
<textarea id="textarea-incident-note" name="resolution-note" rows="4" readonly aria-describedby="textarea-incident-note-description">Rolled back release 2026.09.3 at 14:12 UTC.
Root cause: connection pool exhausted by a retry loop in the billing worker.
Follow-up tracked in OPS-4412.</textarea>
</div>
</forma-textarea>
Click or tap the code once to select all of it, then copy.
Short profile bio with a limit
A compact two-row field with a hard native character limit and spell checking left on. The limit is stated in the description because maxlength silently stops input.
<forma-textarea class="forma-component-tag">
<div class="forma-field">
<label class="forma-field__label" for="textarea-bio">Short bio</label>
<span class="forma-field__description" id="textarea-bio-description">Shown on your public profile. Up to 160 characters.</span>
<textarea id="textarea-bio" name="bio" rows="2" maxlength="160" spellcheck="true" aria-describedby="textarea-bio-description">Platform engineer. Keeps the deploy pipeline boring.</textarea>
</div>
</forma-textarea>
Click or tap the code once to select all of it, then copy.
Mobile
Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.
Mobile feedback form
A feedback textarea at phone width with a submit button below it. The field fills the width and grows only as tall as its rows until the user resizes it.
Static specimen. Submitting or resetting it needs the consuming application's form handling, which this documentation does not have. Its controls are shown for their markup and appearance and cannot be operated here.
What changes at narrow widths
- The textarea fills the phone width;
max-inline-size: 100%stops the resize handle from widening it past the screen. - Height comes from
rows, so the on-screen keyboard leaves the label and the start of the text visible. - Long labels and descriptions wrap above the field.
- The submit button keeps a 44px minimum height below the field.
- Landscape orientation only widens the field; the number of rows stays the same.
<forma-textarea class="forma-component-tag">
<form class="forma-stack" action="/feedback" method="post">
<div class="forma-field">
<label class="forma-field__label" for="textarea-mobile-feedback">What could we do better?</label>
<span class="forma-field__description" id="textarea-mobile-feedback-description">Do not include passwords or personal data.</span>
<textarea id="textarea-mobile-feedback" name="feedback" rows="6" aria-describedby="textarea-mobile-feedback-description"></textarea>
</div>
<button type="submit">Send feedback</button>
</form>
</forma-textarea>
Click or tap the code once to select all of it, then copy.
Mobile · 320px
The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.
API and configuration
Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.
| Attribute | On | Values | Default | Description |
|---|---|---|---|---|
for | label.forma-field__label | id of the textarea | — | Associates the visible label so it is the accessible name. |
name | textarea | string | — | Form field name used on submission. |
rows | textarea | integer | 2 (browser default) | Initial visible line count; sets the starting height. |
maxlength | textarea | integer | — | Native hard limit; the browser stops input at the limit without an error, so state the limit in the description. |
required | textarea | boolean | absent | Native constraint: the form will not submit while empty. |
readonly | textarea | boolean | absent | Focusable, selectable and submitted, but not editable. |
spellcheck | textarea | true | false | browser default | Turns spelling marks on or off. |
aria-describedby | textarea | id list | — | Links the description and any validation message. |
aria-invalid | textarea | true | absent | Set by the application while a linked validation message is shown. |
| Keys | Result |
|---|---|
| Tab / Shift+Tab | Moves focus into and out of the textarea. Tab never inserts a tab character. |
| Enter | Inserts a line break. It does not submit the form. |
| Event | Description |
|---|---|
input / change / invalid | Native textarea events. Forma adds none. |
Form behavior
A native textarea: submits its text (with line breaks) under name, participates in required and maxlength/minlength validation, restores its initial content on form reset, and is excluded when disabled.
States
| State | How it is expressed | Presentation |
|---|---|---|
| Default | no state attributes | Functional border, full width, height from rows. |
| Focus | :focus-visible | Foundation two-tone focus ring. |
| Invalid | aria-invalid="true" plus a linked .forma-validation-message | The message below the field carries the error with a non-color mark; the textarea itself is not restyled. |
| Read-only | readonly attribute | Native behavior with no distinct Forma styling; the description says why it is locked. |
| Disabled | disabled attribute | Skipped by focus and not submitted; Forma adds no dimmed treatment, so explain it in the description. |
Accessibility
Forma provides
- Real label/for association in the canonical structure.
- 44px minimum height, full-width target and the shared two-tone focus ring.
- Borders map to CanvasText in forced-colors mode.
Your application supplies
- Provide a visible label and state any length limit or content restriction in the description.
- Link errors with aria-describedby and set aria-invalid only while an error is shown.
- If you add a live remaining-characters count, announce it politely and sparingly (for example near the limit), not on every keystroke.
Responsive behavior
- The textarea is
inline-size: 100%withmax-inline-size: 100%, so it follows its container and user resizing cannot cause horizontal page overflow. - Height is intrinsic from
rows; there are no breakpoints. - Long unbroken text wraps inside the control; the page does not scroll sideways.
Motion
- No animation: the textarea, label and description do not transition. Resizing follows the pointer directly.
Usage guidance
Do
- Size rows to the expected answer so users can judge how much to write.
- Keep what the user typed when showing an error.
Avoid
- Submitting on Enter; users expect Enter to add a new line in a textarea.
- Disabling resize without a reason; some users need a taller field to review their text.
Verification specimens
Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.