Textarea

Live variants

default

Release notes

Plain text; one change per line.

✕ Say why, not only what.

Markup

<j3w1-textarea id="example-textarea-default"><div class="textarea">
  <label class="textarea-label" for="example-textarea-default-ta-notes">Release notes <span class="textarea-required" aria-hidden="true">*</span><span class="textarea-required sr-only"> required</span></label>
  <div class="textarea-root">
    <textarea class="textarea-input" id="example-textarea-default-ta-notes" rows="3" placeholder="What changed and why" aria-describedby="example-textarea-default-ta-notes-help example-textarea-default-ta-notes-message" name="example-textarea-default-ta-notes">Focus rings now recolour on filled surfaces.
Disabled controls no longer use opacity.</textarea>
  </div>
  <p class="textarea-help" id="example-textarea-default-ta-notes-help">Plain text; one change per line.</p>
  <p class="textarea-message" id="example-textarea-default-ta-notes-message">✕ Say why, not only what.</p>
</div></j3w1-textarea>

with-count

Commit summary

46 / 200

Counts characters, not bytes.

✕ Over the limit.

Markup

<j3w1-textarea id="example-textarea-with-count"><div class="textarea">
  <label class="textarea-label" for="example-textarea-with-count-ta-summary">Commit summary <span class="textarea-required" aria-hidden="true">*</span><span class="textarea-required sr-only"> required</span></label>
  <div class="textarea-root">
    <textarea class="textarea-input" id="example-textarea-with-count-ta-summary" rows="3" maxlength="200" placeholder="Under 200 characters" aria-describedby="example-textarea-with-count-ta-summary-help example-textarea-with-count-ta-summary-count example-textarea-with-count-ta-summary-message" name="example-textarea-with-count-ta-summary">spec: button, link and the basic form controls</textarea>
  </div>
  <p class="textarea-count" id="example-textarea-with-count-ta-summary-count" aria-live="polite">46 / 200</p>
  <p class="textarea-help" id="example-textarea-with-count-ta-summary-help">Counts characters, not bytes.</p>
  <p class="textarea-message" id="example-textarea-with-count-ta-summary-message">✕ Over the limit.</p>
</div></j3w1-textarea>

Install and register

Use the exact version. If npm publication is pending, install the release tarball from the installation guide.

npm install --save-exact @j3w1/ui@4.0.0

import '@j3w1/ui/tokens.css';
import '@j3w1/ui/styles/textarea.css';
import '@j3w1/ui/register/textarea';

Insert the maintained markup above after loading these imports. Its native children provide accessible names and form behavior; the empty custom tag alone does not create a control.

Vue SFC, React, Astro and plain HTML integration →

Copy the complete implementation

npx --package=@j3w1/ui@4.0.0 j3w1-ui copy textarea --out ./vendor/j3w1/textarea

The CLI verifies every file before writing and refuses overwrites. Serve the output over HTTP and open index.html. Keep its modules, CSS, tokens and licence notices together.

Public API

attributes

Name	Type / signature	Meaning
`disabled`	`CustomEvent`	Disable the native controls owned by this instance.
`loading`	`CustomEvent`	Mark the primary control busy and prevent duplicate activation.
`value`	`CustomEvent`	Forwards value to the primary native control.
`required`	`CustomEvent`	Forwards required to the primary native control.
`readonly`	`CustomEvent`	Forwards readonly to the primary native control.
`checked`	`CustomEvent`	Forwards checked to the primary native control.

properties

Name	Type / signature	Meaning
`disabled`	`boolean`	Delegates disabled state to native children.
`name`	`string`	Native control name; application form keys remain explicit.
`value`	`string`	Primary native value; assignment does not fabricate user events.
`checked`	`boolean`	Native checkbox state.
`required`	`boolean`	Native required constraint.
`readOnly`	`boolean`	Native readonly property.
`form`	`HTMLFormElement \| null`	Owning native form. Read only.

methods

Name	Type / signature	Meaning
`refresh`	`(): void`	Reconnect behavior after replacing native child structure.
`focus`	`(options?: FocusOptions): void`	Focus the first usable native control.
`checkValidity`	`(): boolean`	Check owned native constraints.
`reportValidity`	`(): boolean`	Report the first invalid owned control.
`clear`	`(): void`	Clear an editable primary input and emit native input/change.

events

Name	Type / signature	Meaning
`j3w1-change`	`CustomEvent`	Native change from an owned control, alongside the original native event.

Dependencies and verification

Registered components: none. Style dependencies: none.

Package presence establishes an available implementation. Actual passes depend on the tested artifact and environment. Read specification execution evidence; read packed-consumer evidence; inspect the complete state matrix.

Full implementation manifest, API and token dependency closure

Canonical specification

Specimen density

Specimen profile

Textarea `textarea`

Family: Basic forms
Maturity: stable
Priority: R1
Since: 0.1.0
Native control: native <textarea> with <label> — APG pattern
specified
demonstrated

Multi-line free-text entry in the same box as the text field; resizes vertically only and can show a character count.

Report an issue with this component

Tokens

Focus a role to inspect its values; follow its link for persistent usage and source details.

Part	Role	Value	Use
`root.bg`	`color.surface.input`approveduse	`#000000`	Form-control fill.
`root.border`	`color.border.control`approveduse	`#c81a1a`	D-041 owner correction: red control and floating-frame borders, distinct from rose text.
`root.bg-hover`	`color.interaction.hover.bg`approveduse	`#1c1010`	D-041 interaction.hover.bg: color.primitive.modern.hover.
`root.border-focus`	`color.border.active`observeduse	`#e53935`	Active or focused control border.
`root.ring`	`color.interaction.focus.ring`observeduse	`#e53935`	1px dashed focus ring on controls and rows.
`root.ring-invalid`	`color.interaction.focus.ring-container`observeduse	`#ffa2a7`	Focus colour for containers and explicitly mapped filled controls (D-015); component rules determine ring geometry.
`root.border-invalid`	`color.status.danger.border`observeduse	`#e53935`	Danger border, 2px on invalid inputs.
`root.border-disabled`	`color.border.disabled`approveduse	`#482b2b`	D-041 border.disabled: color.primitive.modern.divider.
`root.bg-disabled`	`color.interaction.disabled.bg`approveduse	`#0d0707`	D-041 interaction.disabled.bg: color.primitive.modern.panel.
`root.border-readonly`	`color.border.divider`approveduse	`#482b2b`	D-041 border.divider: color.primitive.modern.divider.
`root.bg-readonly`	`color.surface.canvas`approveduse	`#000000`	Page and terminal background.
`input.text`	`color.text.default`approveduse	`#e99499`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`input.text-disabled`	`color.text.disabled`approveduse	`#a3676b`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`input.placeholder`	`color.text.placeholder`approveduse	`#bd787d`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`input.caret`	`color.code.caret`approveduse	`#ffa2a7`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`input.selection-bg`	`color.interaction.text-selection.bg`observeduse	`#420f0c`	D-041 subdued burgundy selection keeps rose text readable in hosts retaining its foreground.
`input.selection-text`	`color.interaction.text-selection.text`observeduse	`#f4eeee`	::selection text.
`label.text`	`color.text.bright`approveduse	`#ffa2a7`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`label.required-mark`	`color.status.danger.text`observeduse	`#f07178`	D-041 readable error text on neutral surfaces and native warning tints.
`help.text`	`color.text.muted`approveduse	`#d4868b`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`count.text`	`color.text.muted`approveduse	`#d4868b`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`count.text-over`	`color.status.danger.text`observeduse	`#f07178`	D-041 readable error text on neutral surfaces and native warning tints.
`message.text`	`color.status.danger.text`observeduse	`#f07178`	D-041 readable error text on neutral surfaces and native warning tints.

State matrix

Every declared state and combination, statically rendered; the default cell is live. Sizes: compact, comfortable (switch with the density control above).

State	Default	With character count
`default`	Release notes required Focus rings now recolour on filled surfaces. Disabled controls no longer use opacity. Plain text; one change per line. ✕ Say why, not only what.	Commit summary required spec: button, link and the basic form controls 46 / 200 Counts characters, not bytes. ✕ Over the limit.
`hover`
`focus-visible`
`placeholder-shown`
`filled`
`required`
`invalid`
`invalid+focus-visible`
`disabled`
`read-only`

Purpose

Free text longer than a line: descriptions, messages, notes. It shares the text field’s box, states and message so a form reads as one system. Code goes in the code-editor component.

Anatomy

Parts as listed in the anatomy, top to bottom: label, box, count, help; the message takes the help slot visually while help stays in the DOM.

States

State	Visual	Non-colour channel
default	1px `color.border.control` on `color.surface.input`; text `color.text.default`	—
hover	→ `color.interaction.hover.bg`; border unchanged	cursor: text
focus-visible	border → `color.border.active`; 1px dashed `color.interaction.focus.ring` at −2px	the ring
placeholder-shown	`color.text.placeholder`, italic	italic
filled	as default with a value	—
required	`*` after the label in `color.status.danger.text` plus visually hidden “required”	`required`; the mark
invalid	2px `color.status.danger.border`; message with ✕; a count past its limit turns `color.status.danger.text` with the glyph	border 1 → 2px; glyph; `aria-invalid`
invalid+focus-visible	the 2px danger border and a `color.interaction.focus.ring-container` ring at −4px	double boundary
disabled	text `color.text.disabled`, border `color.border.disabled`, fill `color.interaction.disabled.bg`; no resize handle	`disabled`; cursor: not-allowed
read-only	no box: 1px dotted `color.border.divider` bottom edge on `color.surface.canvas`; no resize handle; selectable	`readonly`; dotted edge

Precedence: disabled > invalid > hover; focus-visible is always drawn.

Keyboard

As in the key table. A host that needs literal tabs provides a separate command and documents it. The count is not focusable.

Accessibility

A programmatic label is required. aria-describedby lists help, count and message in that order. The help text states the limit before typing. aria-invalid="true" only after interaction or submit. Text and placeholder meet 4.5:1; control and invalid borders 3:1.

Portability

Hosts without a resize handle grow the box with content up to a maximum and record it. Hosts without dashed outlines draw a solid 1px ring.

Non-examples

Horizontal or free resizing. A box narrower than its label column. A count that only changes colour past the limit. A glow instead of the dashed ring. Rounded corners. Auto-growing with no maximum. Tab inserting a character. Placeholder as the label. Disabling by opacity.

Contrast report

20 declared pairs measured on resolved sRGB values with the WCAG 2.x formula; 0 waived (decorative only), 0 failing. A pass is a design target for the named role, not an application-wide conformance claim.

Pair	State	Kind	Foreground	Background	Ratio	Min	Result
textarea default text	default	text	`color.text.default` `#e99499`	`color.surface.input` `#000000`	9.16	4.5	pass
textarea default border	default	ui	`color.border.control` `#c81a1a`	`color.surface.input` `#000000`	3.62	3	pass
textarea hover text	hover	text	`color.text.default` `#e99499`	`color.interaction.hover.bg` `#1c1010`	8.10	4.5	pass
textarea hover border	hover	ui	`color.border.control` `#c81a1a`	`color.interaction.hover.bg` `#1c1010`	3.20	3	pass
textarea focus-visible text	focus-visible	text	`color.text.default` `#e99499`	`color.surface.input` `#000000`	9.16	4.5	pass
textarea focus-visible border	focus-visible	ui	`color.border.active` `#e53935`	`color.surface.input` `#000000`	4.97	3	pass
textarea focus-visible outline	focus-visible	ui	`color.interaction.focus.ring` `#e53935`	`color.surface.input` `#000000`	4.97	3	pass
textarea placeholder-shown text	placeholder-shown	text	`color.text.placeholder` `#bd787d`	`color.surface.input` `#000000`	6.15	4.5	pass
textarea placeholder-shown border	placeholder-shown	ui	`color.border.control` `#c81a1a`	`color.surface.input` `#000000`	3.62	3	pass
textarea invalid text	invalid	text	`color.text.default` `#e99499`	`color.surface.input` `#000000`	9.16	4.5	pass
textarea invalid border	invalid	ui	`color.status.danger.border` `#e53935`	`color.surface.input` `#000000`	4.97	3	pass
textarea invalid+focus-visible text	invalid+focus-visible	text	`color.text.default` `#e99499`	`color.surface.input` `#000000`	9.16	4.5	pass
textarea invalid+focus-visible border	invalid+focus-visible	ui	`color.status.danger.border` `#e53935`	`color.surface.input` `#000000`	4.97	3	pass
textarea invalid+focus-visible outline	invalid+focus-visible	ui	`color.interaction.focus.ring-container` `#ffa2a7`	`color.surface.input` `#000000`	10.98	3	pass
textarea read-only text	read-only	text	`color.text.default` `#e99499`	`color.surface.canvas` `#000000`	9.16	4.5	pass
validation message on the panel surface	—	text	`color.status.danger.text` `#f07178`	`color.surface.default` `#0d0707`	6.98	4.5	pass
help and count on the panel surface	—	text	`color.text.muted` `#d4868b`	`color.surface.default` `#0d0707`	7.22	4.5	pass
disabled text (exempt; house floor 3:1)	disabled	ui	`color.text.disabled` `#a3676b`	`color.interaction.disabled.bg` `#0d0707`	4.48	3	pass
disabled border (exempt)	disabled	ui	`color.border.disabled` `#482b2b`	`color.interaction.disabled.bg` `#0d0707`	1.58	1	pass
read-only bottom edge (decorative; the field has no box)	read-only	ui	`color.border.divider` `#482b2b`	`color.surface.canvas` `#000000`	1.66	1	pass

Keys

Key	Action
`Tab / Shift+Tab`	Moves focus in and out; Tab never inserts a tab character.
`Enter`	Inserts a line break; never submits.
`Ctrl+Enter / Cmd+Enter`	May submit the owning form when the host binds it; announced in the help text.

For agents

Component JSON ·Implementation brief ·Build a task kit ·

Stress fixtures: FX-LONG FX-320 FX-ZOOM-200 FX-I18N FX-RTL FX-RM FX-HC FX-TOUCH FX-DENSITY FX-OVERFLOW FX-STATE-MATRIX

j3w1 / theme

j3w1 / command

Live variants

default

with-count

Install and register

Copy the complete implementation

Public API

attributes

properties

methods

events

Dependencies and verification

Canonical specification

Textarea `textarea`

Tokens

State matrix

Purpose

Anatomy

States

Keyboard

Accessibility

Portability

Non-examples

Contrast report

Keys

For agents

Live variants

default

with-count

Install and register

Copy the complete implementation

Public API

attributes

properties

methods

events

Dependencies and verification

Canonical specification

Textarea textarea

Tokens

State matrix

Purpose

Anatomy

States

Keyboard

Accessibility

Portability

Non-examples

Contrast report

Keys

For agents

Textarea `textarea`