Textarea

When to use

Use textarea for text that can naturally run to several lines, such as a description, a comment, or a message. For a single line of input, such as a name, an email, or a search term, input is the right-sized fit. Only turn on the formatting mode when the resulting text is actually going to be rendered back somewhere, since otherwise the raw formatting delimiters just leak through as plain text.

Install & usage

Pick a framework in the toolbar above and these snippets adapt.

npm install @eunomia/elements

import "@eunomia/elements/textarea.js";
import "@eunomia/elements/label.js";

<eun-textarea label="Description" placeholder="Tell us more…"></eun-textarea>

npm install @eunomia/elements

<script type="module">
  import "@eunomia/elements/textarea.js";
</script>

<eun-textarea label="Description"></eun-textarea>

npm install @eunomia/elements

import "@eunomia/elements/textarea.js";

function DescriptionField() {
  return <eun-textarea label="Description" name="description" />;
}

npm install @eunomia/elements

"use client";
import "@eunomia/elements/textarea.js";

export function DescriptionField() {
  return <eun-textarea label="Description" name="description" />;
}

npm install @eunomia/elements

<script setup>
  import "@eunomia/elements/textarea.js";
</script>

<template>
  <eun-textarea label="Description" name="description"></eun-textarea>
</template>

npm install @eunomia/elements

import { CUSTOM_ELEMENTS_SCHEMA, Component } from "@angular/core";
import "@eunomia/elements/textarea.js";

@Component({
  selector: "app-description-field",
  template: `<eun-textarea
    label="Description"
    name="description"
  ></eun-textarea>`,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class DescriptionFieldComponent {}

Alternatives

Guidance

Live testing

Properties

Basic

<eun-textarea label="Description" placeholder="Tell us more…"></eun-textarea>

document
  .querySelector("eun-textarea")
  .addEventListener("eunchange", (event) => {
    console.log(event.target.value);
  });

Auto-resize vs. fixed rows

<eun-textarea label="Auto-resize (default)"></eun-textarea>
<eun-textarea label="Fixed rows" rows="3"></eun-textarea>

Without rows, the field grows (and shrinks back) to fit its content as you type. Set a fixed rows to cap the height instead, and the field then falls back to native vertical resizing/scrolling, exactly like a plain <textarea rows="3">.

States

Disabled

<eun-textarea
  label="Description"
  disabled
  value="Can't be edited or submitted."
></eun-textarea>

Readonly

<eun-textarea
  label="Description"
  readonly
  value="Focusable and submitted, but not editable."
></eun-textarea>

Error and validation state

<eun-textarea
  label="Description"
  required
  hint="This field can't be empty"
></eun-textarea>

document.querySelector("eun-textarea").validators = [
  {
    isValid: (value?: string) => (value?.trim().length ?? 0) <= 500,
    message: "Keep it under 500 characters",
  },
];

Character limit counter

Setting maxlength shows a live counter under the field, right-aligned, independent of formatting. It measures the raw value length normally, or the plain-text length (Markdown-lite markup stripped out) when formatting is on, so applying Bold/Italic/color never silently eats into the user's remaining budget.

<eun-textarea label="Short bio" maxlength="80"></eun-textarea>

<eun-textarea
  label="Short bio (formatting)"
  formatting
  maxlength="80"
></eun-textarea>

Past maxlength, a plain field simply can't be typed into further (the native constraint). The formatting surface enforces the same limit by blocking further insertion once reached (replacing an existing selection still works even right at the limit), since a contenteditable element has no native maxlength of its own to rely on.

Variants

<eun-textarea label="Outline" variant="outline"></eun-textarea>
<eun-textarea label="Fill" variant="fill"></eun-textarea>
<eun-textarea label="Underline" variant="underline"></eun-textarea>

Part of the shared vocabulary covered in Variants, alongside every other component that reuses it.

Formatting toolbar

Set formatting to switch the field to a small rich-text editor: a toolbar above it (Bold/Italic/Underline, text alignment, text color, highlight color) and a contenteditable surface instead of a plain <textarea>. Select some text and click a button, or use Ctrl+B/I/U (Cmd on macOS), the same shortcuts as any other rich-text editor, to apply it. Unlike a plain text field, the selection actually turns bold/italic/underlined/colored right there as you edit, with no **/*/__ delimiters ever shown. value still carries that same lightweight Markdown-lite markup underneath (so it keeps round-tripping through formatRichText, storage, eunchange, etc. exactly as before), only the editing surface itself changed.

<eun-textarea label="Comment" formatting></eun-textarea>

const comment = document.querySelector("eun-textarea");
comment.addEventListener("eunchange", () => {
  console.log(comment.value); // e.g. "This is **bold** text"
});

Only one mark is ever toggled per click: clicking Bold never touches whatever Italic/Underline/color state the selection already had, so they all combine freely (bold and italic and underlined and colored, all at once, on the same text). With a real selection, a button (or a picked color) applies to that selection immediately. With nothing selected, a plain blinking cursor, every button and picker instead becomes a pending mark for whatever gets typed next, the same "click Bold, then type, and the new text comes out bold" behavior any rich-text editor's toolbar has. It stays pending across multiple characters (and combines with other pending marks) until toggled off again or the cursor moves away untouched.

Text alignment

<eun-textarea label="Announcement" formatting></eun-textarea>

document.querySelector("eun-textarea").value =
  "[align:center]\nCentered by default…";

Unlike Bold/Italic/Underline/color, alignment is a single, whole-field setting (not per-paragraph, and not selection-dependent). Picking one applies to the entire field's content at once, stored as a leading [align:value] directive line in value (omitted entirely for the default start, to keep the common case clutter-free):

document.querySelector("eun-textarea").value;
// "[align:center]\nCentered by default…"

Text color and highlight

<eun-textarea label="Note" formatting></eun-textarea>

Both pickers open a small popover of seven named swatches (plus a "Default" one to clear the mark), not a free color picker, so every choice stays legible and consistent with the rest of the design system. Selecting one wraps the current selection in {color=name}...{/color} (text color) or {highlight=name}...{/highlight} (background highlight), and picking "Default" removes whichever mark that picker manages from the selection. Combine freely with Bold/Italic/Underline: **{color=red}bold and red{/color}** renders and round-trips correctly, nested marks included.

Localizing the toolbar

Every button and picker has its own overridable accessible label.

<eun-textarea
  label="Commentaire"
  formatting
  format-toolbar-label="Mise en forme du texte"
  format-bold-label="Gras"
  format-italic-label="Italique"
  format-underline-label="Souligné"
  format-align-label="Alignement du texte"
  format-align-start-label="Aligner à gauche"
  format-align-center-label="Centrer"
  format-align-end-label="Aligner à droite"
  format-align-justify-label="Justifier"
  format-text-color-label="Couleur du texte"
  format-highlight-label="Surlignage"
  format-color-clear-label="Aucune"
></eun-textarea>

Formatting and readonly-available

Combined with readonly-available, the static display renders the Markdown-lite value as real formatted text, through the same formatRichText utility exported from @eunomia/elements, instead of showing the raw **/*/__ delimiters. Click into it to switch back to the editable field and its toolbar.

<eun-textarea label="Bio" formatting readonly-available></eun-textarea>

document.querySelector("eun-textarea").value =
  `**Product designer** based in *Lyon*.

- 8 years of experience
- Speaks French and English`;

document
  .querySelector("eun-textarea")
  .addEventListener("euncommit", (event) => save(event.target.value));

Bullet lists (- item) and [label](url) links are also recognized by formatRichText when read back. The toolbar itself just doesn't have buttons for those two, so type them directly.

Click to edit

Set readonly-available to let a field switch between a static, clickable display of its current value and a real editable text area, instead of always being one or the other.

<eun-textarea
  readonly-available
  label="Bio"
  value="Product designer based in Lyon."
></eun-textarea>

document
  .querySelector("eun-textarea[readonly-available]")
  .addEventListener("euncommit", (event) => save(event.target.value));

The static display is clickable and keyboard-activatable (Enter/Space) to enter edit mode. Confirming re-runs validation first: an invalid value stays in edit mode instead of committing. See the Accessibility tab for the full keyboard flow.

Theming

eun-textarea shares the same --field-* custom properties as eun-input (and, eventually, eun-select). Override them once for a consistent look across every text-like field in an app, or per-instance for a one-off, including a --field-shadow for a custom box-shadow (none by default).

<eun-textarea
  label="Custom"
  class="custom-textarea"
  value="Themed field"
></eun-textarea>

.custom-textarea {
  --field-border-radius: 16px;
  --field-border-color-focus: #be185d;
  --field-focus-outline-color: #be185d;
  --field-shadow: 0 4px 12px rgba(190, 24, 77, 0.25);
}

Keyboard interactions

When focus is on the plain field (formatting unset):

When focus is on the formatting surface (a contenteditable element, field not in its readonly display):

On the toolbar (formatting, field not in its readonly display):

On the read-only click-to-edit display (readonly-available, not editing):

Focus indicator

The field renders a :focus-visible outline (--field-focus-outline-color, falling back to --eun-color-primary-500) that switches to --field-error-color while invalid, so the color itself communicates validity state to sighted keyboard users, not just the border. This is true of both the plain field and the formatting surface, since they share the same #field styling. The underline variant suppresses this outline (the border-color change is kept as the sole focus indicator there) since an outline would visually clash with the bottom-only border. Each color picker's trigger and swatch buttons render their own visible focus outline too.

Aria attributes

Plain field (formatting unset):

• aria-invalid="true"|"false": kept in sync with valid
• aria-required: set natively by the underlying required attribute
• aria-label: set from the label property directly on the native field, for the same reason described in eun-input's own Accessibility tab (aria-labelledby can't cross the shadow-root boundary between the field and eun-label's own rendered text). If you only slot custom label content instead of using the property, set your own aria-label on eun-textarea to match.
• aria-describedby: references the hint/error #description and/or the character counter (#char-count, when maxlength is set), whichever are actually rendered. See "Character counter" below for why both can be referenced at once.

formatting surface: a contenteditable element has none of the above natively, so every one of them is set explicitly instead, to the same effect:

• role="textbox" aria-multiline="true": the standard ARIA pattern for a rich-text editing surface (see the Reference links below)
• aria-required="true": only when required, mirroring the native attribute's implicit semantics on the plain field
• aria-invalid, aria-label, aria-describedby: same as the plain field, above
• contenteditable="false": whenever disabled or readonly. The element stays focusable and its content selectable/copyable, just not editable (see "Disabled vs. readonly" below).

Toolbar and pickers (see "Formatting toolbar and the readonly display" and "Color and highlight pickers" below for the full behavioral detail behind each of these):

• The Bold/Italic/Underline toggle group renders role="group" (filter mode) with its own aria-label (formatToolbarLabel). Each button is role="checkbox" with aria-checked reflecting whether that format currently wraps the selection (or is pending, see "Pending marks" below).
• The alignment toggle group renders role="radiogroup" (exclusive/single mode) with its own aria-label (formatAlignLabel). aria-checked reflects the field's current whole-field alignment. Its individual buttons are still role="checkbox", not role="radio", a pre-existing characteristic of eun-toggle-group/eun-toggle-item shared by every exclusive-mode toggle group across this library, not specific to this component, see its own Accessibility tab.
• Each color picker's trigger button has aria-haspopup="true" and aria-expanded. Its open popover is role="menu" with its own aria-label (formatTextColorLabel/formatHighlightLabel), and each swatch inside is role="menuitemradio" with aria-checked reflecting whether it's the color currently active at the selection.

Label accessibility

Always set label (or slot equivalent content). A textarea with no accessible name is exactly as disruptive for screen-reader users as an unlabelled single-line input.

Placeholder accessibility

placeholder is never a substitute for label: it vanishes as soon as a value is typed. On the plain field it's the native placeholder attribute (read by screen readers as placeholder text, same as any input). On the formatting surface, a contenteditable element has no native placeholder at all, so it's a separate, plain aria-hidden="true" overlay element positioned over the field and shown only while value is empty, hidden from assistive technology on purpose, exactly like a native placeholder is (announced once on focus by the browser itself for a native field, not repeated on every keystroke, the overlay approach matches that by not being in the accessibility tree at all, relying on aria-label alone to name the field).

Disabled vs. readonly

disabled removes the field from the tab order (tabindex="-1" on the plain field, the same on the formatting surface, plus contenteditable="false") and excludes its value from form submission entirely. The toolbar and both color pickers, if shown, are disabled along with it (a disabled trigger button can't be clicked open, so a color popover can never be showing while disabled). readonly (native readonly attribute on the plain field, reflected as aria-readonly="true"; contenteditable="false" without a tabindex change on the formatting surface, so it stays a real tab stop) keeps the field focusable and its value selectable and submitted. It communicates "you can't change this right now", not "this doesn't apply", and likewise disables the toolbar and both pickers, since there's nothing to apply a format to. Prefer readonly over disabled whenever the value is still meaningful context for the user, and reserve disabled for fields that are genuinely not part of the current interaction at all.

Error and validation state

Error messages replace the hint text in the same #description region (never shown alongside it) and are linked via aria-describedby as described above. On the plain field, required/minlength/maxlength have native constraint-attribute equivalents (a <textarea> has no pattern, type, or numeric range). The formatting surface has no native constraint validation at all (a contenteditable element isn't a form control), so minlength/maxlength are both checked manually there instead, against the plain-text length with every Markdown-lite marker stripped out. required's empty-value check is unaffected either way, since it never depended on the field's own DOM. Reach for validators for anything past those, same as any other field.

Both the border and the focus outline turn to the same error color while invalid, including through hover and focus, not just at rest, on both the plain field and the formatting surface, since they share the same #field styling. The underline variant keeps only the border-color change (see "Focus indicator" above for why its outline is suppressed entirely).

Character counter

Shown under the field whenever maxlength is set (not in the readonly-available static display, only while actually editing), sharing one row with the hint/error #description, description on one side, counter pinned to the other, a purely presentational grouping. There's no ARIA role on that shared row, and aria-describedby already references both ids independently of how they're laid out visually. The counter is never aria-live. It updates on every keystroke, and announcing it that often would be far more disruptive than helpful. A screen-reader user lands on its exact text ("12/280") by navigating to #char-count directly (it's part of aria-describedby) whenever they choose to check it, same as everyone else.

Readonly-available / click-to-edit flow

The static display exposes role="button" and full keyboard access (Tab to reach it, Enter/Space to activate it), so it's operable without a pointer despite looking like plain text. Entering edit mode moves focus to the field automatically (the native field, or the formatting surface), so a keyboard user never has to Tab a second time after activating it. Confirming an edit re-validates first: an invalid value keeps focus in the field and the error message shown, rather than silently discarding the edit or committing bad data.

Formatting toolbar and the readonly display

The Bold/Italic/Underline toggle's pressed state (and each color picker's own border-color indicator, see "Color and highlight pickers" below) is re-measured on every interaction that can move the selection (typing, clicking, arrowing, refocusing) by walking up the DOM from the selection's anchor to the field itself, a faithful reflection of the current selection, never a stale snapshot from the last click. A collapsed selection (a plain cursor, nothing highlighted) still reports whichever formats surround it, matching the "what would typing here continue" convention word processors use.

Two behaviors are deliberately re-implemented from scratch rather than relying on the browser's own defaults, since a hand-rolled contenteditable surface has to own its own document model to stay serializable back to Markdown-lite:

• Paragraphs: pressing Enter is intercepted and always creates a new paragraph explicitly, rather than letting each browser's own (inconsistent) default block-splitting behavior decide.
• Paste: always inserted as plain text, split into one paragraph per line when multi-line. Any rich formatting/HTML on the clipboard is discarded, never inserted as-is. This keeps the field's content limited to the handful of elements the Markdown-lite serializer understands, with no injection surface from arbitrary clipboard content.

formatRichText (used for the formatting and readonly-available static display, and exported from @eunomia/elements for reuse elsewhere, see the Markdown utility page for its full syntax reference) never uses unsafeHTML either. It builds real Lit templates directly from parsed Markdown-lite, so there's no injection surface there either.

One caveat worth knowing: if the value contains a [label](url) link (recognized by formatRichText, though neither the toolbar nor the formatting surface has a way to create one, only pre-existing links in value are recognized when reading it back), the rendered <a> ends up nested inside the static display's own role="button", interactive content inside interactive content, which assistive technology exposes inconsistently. Avoid combining readonly-available with manually-typed links until this is resolved. Plain bold/italic/underline/color/list content has no such issue, since none of those are separately-focusable elements.

Pending marks (formatting with nothing selected)

Toggling a format or picking a color with a real selection applies to that selection immediately, as described above. With nothing selected, a plain blinking cursor, the same controls instead mark themselves pending: an invisible marker is inserted right at the caret, and whatever gets typed next lands inside it, coming out already formatted. Multiple pending marks combine (click Bold, then Italic, then type, and the new text is both). A pending mark stays pending across as many characters as you keep typing, until either toggled off again or the cursor moves away without anything having been typed into it, at which point it's discarded (and the invisible marker cleanly removed, leaving nothing behind).

This has no separate announcement of its own, since there isn't one needed: the exact same aria-checked a screen-reader user already relies on for "is Bold active right where I am" (see "Formatting toolbar and the readonly display" above) is equally accurate whether that's because of a real selection or a pending mark, since both update through the same live DOM-ancestor check. Toggling Bold with nothing selected and having eun-toggle-item[value="bold"] announce as checked is the accessible signal that the next character typed will be bold.

Color and highlight pickers

Each picker follows the Menu Button pattern loosely rather than exactly: role="menu"/role="menuitemradio" communicate "pick one of these mutually-exclusive options" accurately, but unlike a typical application menu, these entries are color swatches with no text label of their own visible on screen. aria-label (each color's own name, e.g. "Red", or formatColorClearLabel for the one that clears the mark) is each swatch's only accessible name, so it always needs to be set (the defaults are already sensible, override them per Localizing the toolbar's example if the rest of the toolbar is localized too).

Each trigger button additionally reflects whichever color (if any) is currently active right where the selection is as its own border color, kept live (see "Formatting toolbar and the readonly display" above), not just computed when the popover happens to be open. This is a sighted-only, supplementary cue, not a replacement for anything accessible. A screen-reader user gets the equivalent information the moment they open the popover, via whichever swatch is announced with aria-checked="true". There's intentionally no separate text alternative for the border color itself, since there's nothing more precise it could announce that opening the popover doesn't already give firsthand.

Opening a picker moves focus to its first swatch ("Default" in visual order). Selecting one (or Escape) closes the popover and returns focus to the field itself, never leaving it stranded on a control that just disappeared.

Fixed rows and scrolling

Same as the plain field's own native rows (native vertical scroll, already fully keyboard-operable, arrow keys/Page Up/Page Down scroll a focused <textarea> natively), the formatting surface's own rows equivalent (a computed fixed height plus overflow-y: auto, since a contenteditable <div> has no native rows) needs no extra ARIA of its own either. It's the same focused, focusable element either way, and moving the caret with arrow keys already scrolls it into view exactly like a native field would.

Reference links

• WAI-ARIA Authoring Practices: Forms patterns
• WAI-ARIA Authoring Practices: Menu Button pattern (the color/highlight pickers)
• WAI Web Accessibility Tutorials: Labeling Controls
• WHATWG HTML: The textarea element
• WHATWG HTML: The contenteditable attribute