GitHub

Textarea

Multiline input with optional auto-resize, packaged with its label and help/error text. Form-associated via ElementInternals; emits a composed change event.

Stable wc import '@esa/ecology/esa-textarea'; Angular usage

Preview

<esa-textarea label="Description" placeholder="Describe the project…" help-text="Plain text only."></esa-textarea>
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@esa/ecology/esa-textarea';

@Component({
  selector: 'app-textarea-demo',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <esa-textarea
      label="Description"
      placeholder="Describe the project…"
      help-text="Plain text only."
    ></esa-textarea>
  `,
})
export class TextareaDemo {}

Rows + auto-resize

Set a fixed rows count, or add auto-resize to grow with content up to max-rows.

<esa-textarea label="Fixed 5 rows" rows="5" placeholder="Five rows tall"></esa-textarea>
<esa-textarea label="Auto-resize" auto-resize max-rows="8" placeholder="Grows as you type, up to 8 rows"></esa-textarea>
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@esa/ecology/esa-textarea';

@Component({
  selector: 'app-textarea-demo',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <esa-textarea label="Fixed 5 rows" rows="5" placeholder="Five rows tall"></esa-textarea>
    <esa-textarea
      label="Auto-resize"
      auto-resize
      max-rows="8"
      placeholder="Grows as you type, up to 8 rows"
    ></esa-textarea>
  `,
})
export class TextareaDemo {}

Sizes

<esa-textarea label="Extra small" size="xs" placeholder="Extra small"></esa-textarea>
<esa-textarea label="Small" size="sm" placeholder="Small"></esa-textarea>
<esa-textarea label="Medium" size="md" placeholder="Medium"></esa-textarea>
<esa-textarea label="Large" size="lg" placeholder="Large"></esa-textarea>
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@esa/ecology/esa-textarea';

@Component({
  selector: 'app-textarea-demo',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <esa-textarea label="Extra small" size="xs" placeholder="Extra small"></esa-textarea>
    <esa-textarea label="Small" size="sm" placeholder="Small"></esa-textarea>
    <esa-textarea label="Medium" size="md" placeholder="Medium"></esa-textarea>
    <esa-textarea label="Large" size="lg" placeholder="Large"></esa-textarea>
  `,
})
export class TextareaDemo {}

States

<esa-textarea label="Required" required placeholder="Cannot be empty"></esa-textarea>
<esa-textarea label="With error" error-text="A description is required." required></esa-textarea>
<esa-textarea label="Disabled" disabled value="Read only content"></esa-textarea>
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@esa/ecology/esa-textarea';

@Component({
  selector: 'app-textarea-demo',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <esa-textarea label="Required" required placeholder="Cannot be empty"></esa-textarea>
    <esa-textarea label="With error" error-text="A description is required." required></esa-textarea>
    <esa-textarea label="Disabled" disabled value="Read only content"></esa-textarea>
  `,
})
export class TextareaDemo {}

Form participation

The element is form-associated. Submitting logs the FormData entry for notes.

<form>
  <esa-textarea label="Notes" name="notes" placeholder="Type then submit"></esa-textarea>
  <button type="submit">Submit</button>
</form>
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@esa/ecology/esa-textarea';

@Component({
  selector: 'app-textarea-demo',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <form>
      <esa-textarea label="Notes" name="notes" placeholder="Type then submit"></esa-textarea>
      <button type="submit">Submit</button>
    </form>
  `,
})
export class TextareaDemo {}

API

PropTypeDefaultDescription
label string '' Visible label rendered above the textarea.
size 'xs' | 'sm' | 'md' | 'lg' 'md' Control size.
placeholder string '' Placeholder shown when empty.
help-text string '' Helper text shown below the textarea. Property: `helpText`.
error-text string '' Error message; replaces help text and turns the field red when present. Property: `errorText`.
required boolean false Marks the field required and renders an asterisk on the label.
disabled boolean false Disables interaction.
name string | undefined — Form field name — the key this control submits under.
rows number 3 Initial visible row count.
auto-resize boolean false Grows the textarea to fit content as the user types. Property: `autoResize`.
max-rows number 10 Row cap when auto-resize is on. Property: `maxRows`.
value string '' Current value; mirrored to the form on every input.
minlength number | undefined —
maxlength number | undefined —
autocomplete string '' Autofill hint. The only way to satisfy SC 1.3.5 Identify Input Purpose (AA).
live-error boolean false Announce the error the moment it appears rather than only on focus. Off by default — see the long note on `esa-text-field.liveError` for why (the house pattern is validate-on-submit with `<esa-error-summary>`, and a live region per field races it). Property: `liveError`.

Events

EventTypeDefaultDescription
change CustomEvent<{ value: string }> — Fired on every input. Composed and bubbling; detail.value is the current string.
Binding these events from Angular

Every one of these is a CustomEvent, so the payload is on $event.detail — $event.target.value reads empty, with no error. The names are lowercase and Angular passes them to addEventListener verbatim, so camel-casing one means it never fires.

  • (change)="onChange($event.detail)"

Accessibility

  • Renders a native <textarea> associated to its <label> via for/id.
  • Sets aria-invalid="true" while error-text is present.
  • The required asterisk carries an aria-label="required".
  • Visible focus ring via --focus-ring-* tokens.

Theming surface

Every public token this component reads, extracted from its source at build time, split by blast radius: the hooks that belong to this component, then the shared and system tokens it consumes alongside everything else. The Resolves to column walks each token's real lineage — component → semantic → primitive → raw value — so you can see exactly where re-pointing it lands. A spoke re-skins by overriding these in its theme-<slug>.css; component internals are never edited. No hook for what you need? File it with /request-lego.

Type roles it names

This component does not set a size, weight, face or tracking of its own — it names a composite, and the composite carries all five. A composite is a class rather than a token, so none of it appears in the tables below; re-theme text by re-pointing the token family, not by editing the component.

RoleRe-pointReach
.typography-body-2xs
  • --typography-body-2xs-font-family 'DM Sans', sans-serif via --typography-font-family-sans → --font-family-dm-sans
  • --typography-body-2xs-font-size clamp(0.5rem, 0.44rem + 0.3vw, 0.625rem) via --font-size-050
  • --typography-body-2xs-font-weight 350 via --typography-font-weight-regular → --font-weight-350
  • --typography-body-2xs-letter-spacing 0.01em via --letter-spacing-default
  • --typography-body-2xs-line-height 1.6 via --line-height-normal
+6 more components esa-checkbox, esa-checkbox-group, esa-combobox, esa-input-tag, esa-progress-bar, esa-radio-group
.typography-body-lg
  • --typography-body-lg-font-family 'DM Sans', sans-serif via --typography-font-family-sans → --font-family-dm-sans
  • --typography-body-lg-font-size clamp(0.875rem, 0.77rem + 0.52vw, 1.125rem) via --font-size-300
  • --typography-body-lg-font-weight 350 via --typography-font-weight-regular → --font-weight-350
  • --typography-body-lg-letter-spacing 0.01em via --letter-spacing-default
  • --typography-body-lg-line-height 1.8 via --line-height-relaxed
+7 more components esa-breadcrumbs, esa-checkbox, esa-checkbox-group, esa-combobox, esa-input-tag, esa-radio-group, esa-select
.typography-body-md
  • --typography-body-md-font-family 'DM Sans', sans-serif via --typography-font-family-sans → --font-family-dm-sans
  • --typography-body-md-font-size clamp(0.75rem, 0.66rem + 0.44vw, 0.9375rem) via --font-size-200
  • --typography-body-md-font-weight 350 via --typography-font-weight-regular → --font-weight-350
  • --typography-body-md-letter-spacing 0.01em via --letter-spacing-default
  • --typography-body-md-line-height 1.6 via --line-height-normal
+28 more components esa-app-shell, esa-breadcrumbs, esa-card, esa-checkbox, esa-checkbox-group, esa-collapsible, esa-combobox, esa-command-palette, esa-confirm-dialog, esa-container, esa-danger-zone, esa-dialog, esa-dropdown-menu, esa-empty-state, esa-entity-search, esa-form-field, esa-header-nav, esa-input-tag, esa-nav-dropdown, esa-page-header, esa-popover, esa-progress-bar, esa-radio-group, esa-select, esa-side-dialog, esa-snackbar-item, esa-switch-toggle, esa-tab-layout
.typography-body-sm
  • --typography-body-sm-font-family 'DM Sans', sans-serif via --typography-font-family-sans → --font-family-dm-sans
  • --typography-body-sm-font-size clamp(0.6875rem, 0.61rem + 0.38vw, 0.875rem) via --font-size-150
  • --typography-body-sm-font-weight 350 via --typography-font-weight-regular → --font-weight-350
  • --typography-body-sm-letter-spacing 0.01em via --letter-spacing-default
  • --typography-body-sm-line-height 1.6 via --line-height-normal
+20 more components esa-alert-box, esa-breadcrumbs, esa-button-toggle, esa-card, esa-checkbox-group, esa-combobox, esa-command-palette, esa-date-picker, esa-empty-state, esa-file-upload, esa-form-field, esa-input-tag, esa-link-column, esa-loading-overlay, esa-progress-bar, esa-radio-group, esa-search-panel, esa-select, esa-stat, esa-text-field
.typography-body-xs
  • --typography-body-xs-font-family 'DM Sans', sans-serif via --typography-font-family-sans → --font-family-dm-sans
  • --typography-body-xs-font-size clamp(0.625rem, 0.56rem + 0.32vw, 0.75rem) via --font-size-100
  • --typography-body-xs-font-weight 350 via --typography-font-weight-regular → --font-weight-350
  • --typography-body-xs-letter-spacing 0.01em via --letter-spacing-default
  • --typography-body-xs-line-height 1.6 via --line-height-normal
+14 more components esa-breadcrumbs, esa-checkbox, esa-checkbox-group, esa-combobox, esa-command-palette, esa-empty-state, esa-entity-search, esa-field-error, esa-header-nav, esa-input-tag, esa-progress-bar, esa-radio-group, esa-search-panel, esa-select
.typography-label-2xs
  • --typography-label-2xs-font-family 'DM Sans', sans-serif via --typography-font-family-sans → --font-family-dm-sans
  • --typography-label-2xs-font-size clamp(0.5rem, 0.44rem + 0.3vw, 0.625rem) via --font-size-050
  • --typography-label-2xs-font-weight 500 via --typography-font-weight-medium → --font-weight-500
  • --typography-label-2xs-letter-spacing 0.01em via --letter-spacing-default
  • --typography-label-2xs-line-height 1.6 via --line-height-normal
+11 more components esa-button-toggle, esa-checkbox-group, esa-color-picker, esa-combobox, esa-date-picker, esa-form-field, esa-input-tag, esa-progress-bar, esa-radio-group, esa-range-slider, esa-text-field
.typography-label-lg
  • --typography-label-lg-font-family 'DM Sans', sans-serif via --typography-font-family-sans → --font-family-dm-sans
  • --typography-label-lg-font-size clamp(0.875rem, 0.77rem + 0.52vw, 1.125rem) via --font-size-300
  • --typography-label-lg-font-weight 500 via --typography-font-weight-medium → --font-weight-500
  • --typography-label-lg-letter-spacing 0.01em via --letter-spacing-default
  • --typography-label-lg-line-height 1.6 via --line-height-normal
+12 more components esa-breadcrumbs, esa-button-toggle, esa-checkbox-group, esa-color-picker, esa-combobox, esa-date-picker, esa-form-field, esa-input-tag, esa-radio-group, esa-range-slider, esa-select, esa-text-field
.typography-label-md
  • --typography-label-md-font-family 'DM Sans', sans-serif via --typography-font-family-sans → --font-family-dm-sans
  • --typography-label-md-font-size clamp(0.75rem, 0.66rem + 0.44vw, 0.9375rem) via --font-size-200
  • --typography-label-md-font-weight 500 via --typography-font-weight-medium → --font-weight-500
  • --typography-label-md-letter-spacing 0.01em via --letter-spacing-default
  • --typography-label-md-line-height 1.6 via --line-height-normal
+33 more components esa-app-bar, esa-breadcrumbs, esa-button-group, esa-button-toggle, esa-card, esa-checkbox-group, esa-color-picker, esa-combobox, esa-command-palette, esa-confirm-dialog, esa-danger-zone, esa-date-picker, esa-dialog, esa-empty-state, esa-entity-search, esa-file-upload, esa-filter-container, esa-form-field, esa-header-nav, esa-input-tag, esa-link-column, esa-page-header, esa-pillbox, esa-popover, esa-progress-bar, esa-radio-group, esa-range-slider, esa-select, esa-side-dialog, esa-sidebar-nav, esa-stat, esa-text-field, esa-tooltip
.typography-label-xs
  • --typography-label-xs-font-family 'DM Sans', sans-serif via --typography-font-family-sans → --font-family-dm-sans
  • --typography-label-xs-font-size clamp(0.625rem, 0.56rem + 0.32vw, 0.75rem) via --font-size-100
  • --typography-label-xs-font-weight 500 via --typography-font-weight-medium → --font-weight-500
  • --typography-label-xs-letter-spacing 0.01em via --letter-spacing-default
  • --typography-label-xs-line-height 1.6 via --line-height-normal
+14 more components esa-breadcrumbs, esa-button-toggle, esa-checkbox-group, esa-color-picker, esa-combobox, esa-date-picker, esa-entity-search, esa-form-field, esa-input-tag, esa-progress-bar, esa-radio-group, esa-range-slider, esa-select, esa-text-field

Wired to this component

None. This component has no hooks of its own — it themes entirely through the shared tokens below, so every override here also moves its siblings.

Shared tokens it reads

Owned by a family or by the semantic layer. Still overridable — but scope the override (esa-foo { --form-border-color: … }) unless you mean to move everything that reads it. Reach says what else that is.

Token Reach Resolves to
--focus-ring-color component focus ring group · +34 more #3e9b4f via --color-border-default-focus → --color-grass-10
--focus-ring-offset component focus ring group · +31 more 2px
--focus-ring-width component focus ring group · +35 more 2px via --border-width-focus → --border-width-200
--form-border-color component forms group · +11 more one role per property, so a theme can move the ring's weight and its colour independently. Tier 3's --focus-ring-width now reads this instead of holding a bare 2px, which is the same shape --focus-ring-color has always had (a thin tier-3 alias over a tier-2 role) — width was simply never given the tier-2 half. * * This role was rejected once, and the rejection is worth recording because its PREMISE was wrong rather than its reasoning. The argument against an `emphasis` width was that every 2px border in the kit is micro-geometry — spinner rings, the kbd keycap lip, a chevron. The focus ring was not in that enumeration and does not fit it: 33 components render it, more than read any other tier-3 token, and it is not micro-geometry but an accessibility affordance whose weight is a legitimate brand axis (a spoke that needs a heavier ring for contrast has to be able to reach it). It is also not a `border` in any component — every consumer paints it with `outline` or `box-shadow` — which is precisely why a survey of BORDERS missed it. The name still says `border` because tier 2 already calls the ring's colour --color-border-default-focus via --color-border-default
--form-border-color-focus component forms group · +11 more #3e9b4f via --color-border-default-focus → --color-grass-10
--form-border-color-hover component forms group · +3 more #bbbbbb via --color-border-default-strong → --color-gray-8
--form-border-width component forms group · +10 more 1px via --border-width-default → --border-width-100
--form-error-border-color component forms group · +9 more #ce2c31 via --color-background-utility-danger → --color-red-11
--form-error-color component forms group · +9 more #ce2c31 via --color-content-utility-danger → --color-red-11
--form-help-color component forms group · +9 more #646464 via --color-content-default-secondary → --color-gray-11
--form-help-gap component forms group · +5 more 0.25rem via --spacing-100
--form-label-color component forms group · +7 more #646464 via --color-content-default-secondary → --color-gray-11
--form-label-gap component forms group · +2 more 0.25rem via --spacing-100
--form-placeholder-color component forms group · +4 more #646464 via --color-content-default-secondary → --color-gray-11
--form-text-color component forms group · +6 more #202020 via --color-content-default → --color-gray-12
--color-background-disabled semantic every component #f0f0f0 via --color-gray-3
--color-background-field semantic every component rgba(0, 0, 0, 0)
--color-border-disabled semantic every component #d9d9d9 via --color-gray-6
--color-content-disabled semantic every component #8d8d8d via --color-gray-9
--color-content-utility-danger semantic every component #ce2c31 via --color-red-11
--radius-md semantic every component 0.5rem via --radius-200
--radius-sm semantic every component 0.25rem via --radius-100
--transition-fast semantic every component 150ms via --duration-150
--spacing-100 primitive every component 0.25rem
--spacing-200 primitive every component 0.5rem
--spacing-250 primitive every component 0.625rem
--spacing-300 primitive every component 0.75rem
--spacing-400 primitive every component 1rem