An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:TextArea authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-27 owners: [cixzhang] review_triggers: [ public-api, behavior, layout, theming, accessibility, component-slots, react-runtime, interaction, styling, compatibility, ] verified_by: [ packages/core/src/TextArea/TextArea.test.tsx, packages/core/src/inputFontFloor.test.ts, packages/core/src/TextArea/TextArea.fr10.test.tsx, packages/core/src/TextInput/tests/TextInput.a11y.test.tsx, packages/core/src/TextInput/tests/TextInput.a11y.chromium.spec.ts, packages/core/src/theme/themingTargets.test.ts, scripts/check-knowledge.mjs, packages/core/src/tests/BusyOwnerAnnouncement.test.tsx, packages/core/src/hooks/useInputStatusIcon.test.tsx, ] modules: [] families: [family:input-fields] design_specs: [] architecture: [ architecture:component-size-cascade, architecture:component-theming-surface, architecture:internationalization, architecture:public-component-api, ] contributing: []
system_specs: [spec:AST-085, spec:AST-086]
TextArea component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | TextArea is a controlled multi-line field with Field props, rows, size, status, start icon, maxLength counter, onChange, changeAction, isLoading, disabled and read-only states, hasSpellCheck, the touch-keyboard props enterKeyHint, inputMode, autoCapitalize, and hasAutoCorrect (FR13), and the input-family part props. |
| Behavior | Typing calls onChange, then an optional changeAction with an optimistic value and one busy Spinner. maxLength adds a visual character counter that warns but never blocks typing. |
| End-user impact | People write longer text with a live count that is announced only when they near or pass the limit. Keyboard and screen-reader users can reach a disabled field and its reason. An error without a message has no text. |
| Builder impact | Callers can choose the touch keyboard, its Return key label, capitalization, and correction (FR13); an unset prop leaves the field as it is. |
| Compatibility/readiness | The touch-keyboard props are additive, a patch [feat] (spec:AST-017 FR5, FR7). Otherwise the record states shipped behavior. Attached status on a tall surface, dropped grouped container props, text under the counter, an error without text, and a color-only detached status are listed under Current-state impact. |
| Review checks | Reject a counter that truncates input or counts code units, an announcement on every keystroke, text that runs under the icons or counter, a disabled field that leaves the tab order or submits, or root styling props. |
| Governing rules | family:input-fields FR4–FR6, FR8–FR10, AV3; spec:AST-085 FR1–FR3, FR6; spec:AST-086 FR8; architecture:component-theming-surface; component:TextInput FR16, DEC-1; architecture:public-component-api INV2, INV3, INV25. |
This table is a review projection; the body below is authoritative.
Intent
TextArea collects multi-line text. It owns the native textarea, its change and
Action pipeline, the character counter, overlay icon placement, and disabled
and read-only behavior under family:input-fields. Consumer usage lives in
TextArea.doc.mjs.
Compatibility and migration
- Released default preserved:
yes;rows={3}, spellcheck on,size="md",statusVariant="attached" - Compatibility class: additive; the optional touch-keyboard props (FR13) are
a patch
[feat](spec:AST-017FR5, FR7). Unset, they render nothing, so no released default or DOM output changes. TextArea emits only thetext-area,text-area-control, andtext-area-countertargets - Controlled/uncontrolled behavior: controlled only;
valueis required, and the field shows an optimistic value only while achangeActionis pending - Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
Ownership boundary
Owns
- The painted input container, native textarea, and character counter, with
their
text-area,text-area-control, andtext-area-countertargets. - The change and Action pipeline and the busy state.
- The counter's counting, over-limit cue, and announcements.
- Overlay placement of the start icon, Spinner, status icon, and counter, and the text padding that keeps text clear of them.
- Disabled, disabled-reason, and read-only behavior.
- The touch-keyboard attributes of the native textarea (FR13).
Does not own / non-goals
- Label and attached/detached validation-message presentation — owned by
Field under
family:input-fields(shared owner section) andcomponent:FieldStatus. - The tooltip-variant status surface — owned by Tooltip.
- Standard start-icon presentation and the shared on-field status icon — owned
by
component:Iconand the shared input-field status icon underfamily:input-fields, respectively. - Loading-indicator presentation — owned by
component:Spinner. - Caller-provided custom start content outside Icon's supported source forms.
- InputGroup — TextArea is not admitted (
family:input-fieldsadoption). - Enforcing
maxLength— the counter is visual only.
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| Rows | positive integer | Initial visible lines; the user may resize taller. | Always. | 3 |
component:TextArea |
Stable | Passed to the native attribute. |
| Size | sm, md, lg |
Text inset; lg adds block padding. |
Always. | Inherited size, else md |
family:input-fields |
Stable | TypeScript rejects other values. |
| Counter | under, near, over | Character count against maxLength. |
When maxLength is set. |
none | component:TextArea |
Stable | Not applicable. |
| Busy | idle, busy | The value is loading or being saved. | isLoading, or while a changeAction is pending. |
idle | family:input-fields |
Stable | Not applicable. |
| Availability | editable, read-only, disabled | Whether the value can change and submits. | Always; disabled wins. | editable | component:TextArea |
Stable | Not applicable. |
| Touch keyboard | enterKeyHint (EnterKeyHint), inputMode (InputMode), autoCapitalize (AutoCapitalize), hasAutoCorrect (boolean) |
The touch keyboard, its Return key label, capitalization, and correction, as component:TextInput FR16 defines them. |
Always. | unset: no attribute | component:TextArea |
Stable | TypeScript rejects other values. |
Behavioral and layout contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | TextArea renders inside Field (label, description, optional or required marker, label tooltip, status, width) and places the native textarea inside its painted input container. It has no grouped adaptation: inside InputGroup it still renders its own Field box and label, while container* props are dropped (FR12). |
family:input-fields adoption; current source and tests |
| FR2 | The input container carries text-area with data-size, data-status, data-disabled, and data-readonly; the textarea carries text-area-control; the counter carries text-area-counter. Placeholder text is part of the textarea; the over-limit glyph is part of the counter. |
architecture:component-theming-surface; current source and tests |
| FR3 | The textarea shows rows lines (default 3), resizes only vertically, and uses body text, floored at 16 CSS px only on the iOS touch path. lg adds block padding; sm and md share the default inset. |
family:input-fields FR9, AV3; current source and tests |
| FR4 | Editing calls onChange(value, event); unless that call prevents default, changeAction(value, event) then runs in a transition and the field shows the proposed value while the Action is pending, and value once it settles. While isLoading or while the shown value differs from value, the textarea sets aria-busy, a decorative Spinner shows, and the busy start is announced once. |
family:input-fields FR5, FR6; spec:AST-086 FR8; current tests |
| FR5 | With maxLength, a counter showing the character count and the limit renders at the container's bottom end and describes the textarea. It counts user-perceived characters, so a multi-code-point emoji counts once. It never sets the native maxLength and never blocks typing. Over the limit it turns the error color, adds a decorative warning icon, and sets aria-invalid. The counter text MUST come from one catalog message (architecture:internationalization INV1a), with both numbers in the locale's number format. |
Current tests; architecture:internationalization INV1a |
| FR6 | Counter announcements happen when an edit lands in a different zone than the previous edit: entering the last 20% of the limit announces the remaining characters politely; exceeding the limit announces the overage assertively; moving back under announces nothing. Zone tracking starts unset, so the first edit after mount announces the near or over zone it lands in, even when the mounted value was already there. | Current tests |
| FR7 | The start icon renders at the top start, and the Spinner and on-field status icon at the top end; the textarea reserves inline padding for each one that renders (more when both end items show) and bottom padding for the counter, so text never runs under them; the counter's bottom padding clears text only at the end of the scroll range. Implementation gap: with a value longer than rows, the last visible line paints under the counter unless the field is scrolled to the end. A detached status reserves no end space because it renders no on-field icon. |
family:input-fields FR2; current source and tests |
| FR8 | A status paints the status border; error sets aria-invalid. The on-field status icon shows for attached and tooltip placement; a detached status shows its glyph only in the message box, which renders only with a message. The message renders through Field in the chosen placement. Every status MUST show a cue other than color (WCAG 2.2 1.4.1), and an error MUST be identified in text (WCAG 2.2 3.3.1). Implementation gap: TextArea offers attached placement, as its default and explicitly, although family:input-fields FR8 and AV6 allow attached only on a fixed-height control; an error status may have no message; and a detached status without a message shows only the colored border. |
family:input-fields FR8; current tests |
| FR9 | Disabled: aria-disabled="true" and readOnly on the textarea, a kept tab stop, no name (not submitted), no value change, no onPaste, no caller handlers other than focus and blur, a dimmed container, and a keyboard focus ring. With disabledMessage, a reason tooltip opens on hover and keyboard focus and describes the textarea. |
spec:AST-085 FR1–FR3, FR6; family:input-fields FR4; current tests |
| FR10 | Read-only: readOnly, full opacity, focusable, still submitted, never calls onChange. Disabled wins when both are set. |
Current tests |
| FR11 | hasSpellCheck (default on) sets spellcheck; htmlName, autoComplete, hasAutoFocus, and onPaste reach the textarea. A click on the container outside the textarea focuses it, except while disabled or busy. |
Current tests |
| FR12 | Base props reach the textarea and aria-describedby joins TextArea's descriptions; container* reaches the Field box where one renders (in a horizontal-labels FormLayout none renders, and container* has no effect and warns) and control* the input container; root xstyle, className, and style are not accepted. Implementation gap: inside InputGroup the Field box still renders, but container* is dropped with a development warning that no Field box renders. |
family:input-fields FR10; current tests |
| FR13 | enterKeyHint, inputMode, autoCapitalize, and hasAutoCorrect follow component:TextInput FR16 on the textarea: a set prop renders its native attribute (hasAutoCorrect as autocorrect="on" or "off"), an unset prop renders none, the value types are the same exported closed unions EnterKeyHint, InputMode, and AutoCapitalize, and they change only the touch keyboard. Enter inserts a line break whatever the key says. hasSpellCheck keeps FR11. |
component:TextInput FR16, DEC-1 |
Allowed variation
- AV1 — Height. The user may drag the textarea taller; content may grow
past
rows. - AV2 — Start content. Icon-supported values or caller content may fill the start slot.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Default editable | Label, input container, and textarea render. | Value, placeholder, rows, and size |
| Near the limit | Counter visible; one polite remaining-characters announcement. | Count. |
| Over the limit | Error-colored counter with warning icon; aria-invalid; one assertive announcement. |
— |
| Busy with status | Spinner and status icon both at the top end; extra end padding. | Status variant. |
| Disabled with reason | Focusable; read-only; not submitted; reason tooltip. | — |
Transformation and precedence order
- ORD1 — Availability. Disabled, then read-only, then editable.
- ORD2 — Change. Counter zone check,
onChange, then the optimistic value andchangeActionunless prevented. - ORD3 — Description. Caller description, then description, status message (or status tooltip), counter, and disabled reason.
Performance and resources
- PR1 — Counting cost. Characters are counted only when
maxLengthis set: for each edit's proposed value, and again when the shown value ormaxLengthchanges.
Accessibility contract
- AR1 — Name and description. The textarea is labelled by Field and described per ORD3, including the counter.
- AR2 — Counter announcements. FR6; spoken output follows
spec:AST-009. - AR3 — Over-limit cue. The over-limit state has a non-color cue (FR5).
- AR4 — Disabled. FR9 satisfies
spec:AST-085FR1, FR5, and FR6.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Input container | Presents the current painted field boundary. | Current source and public docs | Supporting | FR1, FR2 |
| Text area | Presents and edits the current multi-line value. | Current source and public docs | Prominent | FR1, FR2, FR3 |
| Character counter | Presents current and maximum character counts. | Current source and public docs | Supporting | FR2, FR5 |
| Shared field feedback | Presents current label, standard icons, status, and loading content. | Current shared-component source | Supporting | FR7, FR8 |
Theming anatomy
{
"Label": {
"delegatesTo": {"owner": "component:Field", "target": "field-label"}
},
"Description": {
"none": {
"reason": "unsettled: No current public target reaches the stable Description; future exposure still needs an owner decision"
}
},
"Input container": {"target": "text-area"},
"Text area": {"target": "text-area-control"},
"Placeholder": {"inherits": "text-area-control"},
"Start icon": {
"delegatesTo": {"owner": "component:Icon", "target": "icon"}
},
"Custom start content": {
"none": {
"reason": "intentional: Custom start content is caller-provided ReactNode content outside TextArea's public theming ownership"
}
},
"Spinner": {
"delegatesTo": {"owner": "component:Spinner", "target": "spinner"}
},
"Status icon": {
"delegatesTo": {
"owner": "component:Field",
"target": "input-status-icon"
}
},
"Character counter": {"target": "text-area-counter"},
"Field status message": {
"delegatesTo": {
"owner": "component:FieldStatus",
"target": "field-status"
}
},
"Tooltip status message": {
"delegatesTo": {"owner": "component:Tooltip", "target": "tooltip"}
}
}
Description remains stable consumer anatomy, but no current public target
reaches it; future exposure remains unsettled. Semantic names and icon component
values render through Icon and delegate to its icon target; arbitrary ReactNode
start content is caller-provided and intentionally stays outside TextArea's
public theming ownership. Attached and detached status messages delegate to
FieldStatus, while the tooltip variant delegates its rendered surface to Tooltip.
Family and system relationships
family:input-fieldsowns busy, Transition Actions, disabled reasons, status placement, the focus-zoom floor, prop targets, and block-axis growth; TextArea adopts them and is not InputGroup-compatible.architecture:component-theming-surfaceowns anatomy qualification, factualnonedispositions, composition-preserving ownership, and alias exclusion.- Field, FieldStatus, Icon, Spinner, and Tooltip retain their own target contracts when composed by TextArea.
spec:AST-085owns disabled focusability; TextArea meets it.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, FR3 | TextArea.test.tsx structure, rows, and size cases; inputFontFloor.test.ts |
Default, custom rows, lg |
Removing or regrouping stable parts breaks role, content, or DOM assertions; a missing iOS floor fails. Evidence gap: no test renders TextArea inside InputGroup, or asserts vertical-only resize, the body text size, or the lg padding. |
audit:TextArea/anatomy |
| FR2 | TextArea.test.tsx root-target and theme-state suites; themingTargets.test.ts |
Three local targets; disabled and read-only | A missing class, a missing data-disabled or data-readonly, or source and docs drift, fails. Evidence gap: no test asserts data-size or data-status. |
audit:TextArea/theming |
| FR4 | TextArea.test.tsx change and busy cases; BusyOwnerAnnouncement.test.tsx TextArea cases |
Typing; isLoading |
A wrong onChange payload, no aria-busy, or a busy start announced more than once fails. Evidence gap: no test asserts changeAction after onChange, or the optimistic value. |
audit:TextArea/behavior |
| FR5, FR6, AR2, AR3 | TextArea.test.tsx maxLength suite |
Under, near, over; emoji; controlled typing | Native truncation, code-unit counting, a missing cue, or a missing zone announcement fails. Evidence gap: no test types twice inside a zone or moves back under the limit, so a repeated announcement would pass. | audit:TextArea/accessibility |
| FR7, FR8 | TextArea.test.tsx status, busy-with-status, and statusVariant suites; useInputStatusIcon.test.tsx TextArea tooltip and placement cases |
Attached, detached, tooltip; busy with status | A missing status icon or message, or a missing aria-invalid on error, fails. Evidence gap: no test measures the reserved padding or text under the counter, or renders a detached status without a message. |
audit:TextArea/layout |
| FR9, FR10, ORD1, AR4 | TextArea.test.tsx disabled, disabledMessage, read-only, and form suites; the disabled no-caller-handler case (paste and key) |
Disabled, with reason, read-only, both | A lost tab stop, a submitted disabled value, a caller handler, or an edit fails. | audit:TextArea/accessibility |
| FR11 | TextArea.test.tsx spellcheck, paste, autoComplete, autofocus, click-to-focus suites |
Each prop | A dropped attribute or unfocused click fails. Evidence gap: no test clicks the container while disabled or busy. | audit:TextArea/behavior |
| FR12 | TextArea.fr10.test.tsx |
Standalone; horizontal-labels FormLayout |
A base prop off the textarea, or styling on the wrong part, fails. | audit:TextArea/api |
| FR13 | TextArea.test.tsx touch keyboard traits suite (each prop set and unset; Return stays a line break under any enterKeyHint); textEntryTraits.public.test.ts, run by pnpm typecheck, for the shared unions rejecting an arbitrary or unnarrowed string; TextAreaKeyboardTraits.a11y.chromium.spec.ts for the attributes on the textarea a tap focuses |
Each prop set and unset; a phone viewport with touch emulation | An attribute while unset, a dropped or renamed attribute, or a value type that accepts string fails. |
audit:TextArea/api |
| ORD2, ORD3, PR1 | Evidence gap: the description cases check each id's presence, not the ORD3 order, and no test asserts the counter-zone, change, and Action order, or that counting runs only with maxLength |
— | — | audit:TextArea/behavior |
| AR1 | TextInput.a11y.test.tsx and TextInput.a11y.chromium.spec.ts TextArea states |
Empty with placeholder; error without message | A missing name or description fails; the recorded known failure stops matching when its gap closes. | audit:TextArea/accessibility |
| Theming anatomy map | scripts/check-knowledge.mjs |
Canonical anatomy and current local targets | Canonical-key drift, invalid dispositions or target spelling, alias-backed local claims, or an unclaimed current local target fails validation. | audit:TextArea/theming |
No repository check resolves delegatesTo owner and target pairs; the pairs
above match the current Field, FieldStatus, Icon, Spinner, and Tooltip targets.
Current-state impact
- Attached status on a tall surface (FR8). TextArea offers
attachedstatus placement, as its default and explicitly, whilefamily:input-fieldsFR8 and AV6 allowattachedonly on a fixed-height control. - Grouped container props (FR12). Inside InputGroup, TextArea still renders
its Field box but drops
container*props, warning that no Field box renders. - Text under the counter (FR7). With a value longer than
rows, the last visible line paints under the counter unless the field is scrolled to the end. - Error without text. TextArea accepts an error status without a message, so the error is shown only by color and an icon, against WCAG 2.2 3.3.1. The shared text-input accessibility suite records this as a known failure.
- Color-only detached status (FR8). A
detachedstatus without a message shows only the colored border, against WCAG 2.2 1.4.1.
Decision log
No component-local decision. TextArea applies family:input-fields,
spec:AST-085, and component:TextInput DEC-1.
Open questions
None.
Content boundary
This file does not duplicate consumer prop tables/examples, current audit results, implementation steps, or family/system rules. It links to their owners.