Form inputs

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 rows attribute.
  • 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.

Canonical

Minimal textarea

Rendered from the canonical pattern file.

Describe what changed and why. Plain text, up to 500 characters.
HTML · Minimal textarea Raw HTML for HTML · Minimal textarea
<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

Scenario

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.

The author sees this text. Say what must change before you can approve.

Enter a reason so the author knows what to fix.

HTML · Required rejection reason Raw HTML for HTML · Required rejection reason
<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.

Scenario

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.

Locked because the incident is closed. Reopen the incident to edit.
HTML · Read-only incident note Raw HTML for HTML · Read-only incident note
<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.

Scenario

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.

Shown on your public profile. Up to 160 characters.
HTML · Short profile bio with a limit Raw HTML for HTML · Short profile bio with a limit
<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 example

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.

Viewport width

Frames narrower than the selected width show the component at the width available.

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.
HTML · Mobile feedback form Raw HTML for HTML · Mobile feedback form
<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.

Baseline

Mobile · 320px

The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.

Viewport width

Frames narrower than the selected width show the component at the width available.

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.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
forlabel.forma-field__labelid of the textarea—Associates the visible label so it is the accessible name.
nametextareastring—Form field name used on submission.
rowstextareainteger2 (browser default)Initial visible line count; sets the starting height.
maxlengthtextareainteger—Native hard limit; the browser stops input at the limit without an error, so state the limit in the description.
requiredtextareabooleanabsentNative constraint: the form will not submit while empty.
readonlytextareabooleanabsentFocusable, selectable and submitted, but not editable.
spellchecktextareatrue | falsebrowser defaultTurns spelling marks on or off.
aria-describedbytextareaid list—Links the description and any validation message.
aria-invalidtextareatrueabsentSet by the application while a linked validation message is shown.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves focus into and out of the textarea. Tab never inserts a tab character.
EnterInserts a line break. It does not submit the form.
Events
EventDescription
input / change / invalidNative 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

Textarea states
StateHow it is expressedPresentation
Defaultno state attributesFunctional border, full width, height from rows.
Focus:focus-visibleFoundation two-tone focus ring.
Invalidaria-invalid="true" plus a linked .forma-validation-messageThe message below the field carries the error with a non-color mark; the textarea itself is not restyled.
Read-onlyreadonly attributeNative behavior with no distinct Forma styling; the description says why it is locked.
Disableddisabled attributeSkipped 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% with max-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.