HyTextArea
Usage examples on this page are written for Lit / plain HTML (
<hy-text-area>). The same component ships asHyTextAreain@whitespaceux/harmony-react(native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.
A versatile multi-line text input component with enhanced styling and functionality. Supports validation states, auto-resizing, character limits, and comprehensive accessibility features. Provides a consistent interface for various text area scenarios with built-in error handling.
When to use
- Free text over several lines: a comment, a description, a message.
Do
- Set
rowsto the length most answers have.
When not to use
- A name, an email or a search term:
hy-text-input. - A value from a known set:
hy-selectorhy-combobox. - An address or another multi-part record: one labeled
hy-text-inputper part. - Text that needs headings, lists or emphasis:
hy-markdown-editor. - Answers whose length varies widely:
auto-resize, capped withmax-rows, instead of scrolling in a fixed box.
Accessibility: your part
- Name the field with
label, or witharia-label/aria-labelledbyon the host when nearby text already names it. - Never put instructions in
placeholder. It disappears on the first keystroke. - When
maxlengthis set, tell people the limit before they reach it.
Examples
html
<hy-text-area label="Comments" placeholder="Enter your comments..."></hy-text-area>html
<hy-text-area
label="Description"
helper-text="Provide a detailed description"
rows="6"
maxlength="500"
required
>
</hy-text-area>html
<hy-text-area
label="Bio"
helper-text="A few sentences about you"
warning-message="Long bios are cut off on profile cards"
>
</hy-text-area>
<hy-text-area label="Reason" required error-message="Tell us why you are leaving"></hy-text-area>Narrower than its container — cols states how many characters a line holds
html
<hy-text-area label="Address" cols="32" rows="3"></hy-text-area>html
<hy-text-area label="Feedback" value="This is existing feedback" size="large" auto-resize>
</hy-text-area>API
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
focused | focused | boolean | false | Whether the text area is currently focused. |
disabled | disabled | boolean | false | Disables the text area, preventing user interaction. |
required | required | boolean | false | Marks the text area as required for form validation. |
readonly | readonly | boolean | false | Makes the text area read-only, preventing user editing. |
error | error | boolean | false | Whether the text area is in an error state. |
warning | warning | boolean | false | Warning state: the value is accepted but worth a second look. Paints the warning color and shows warning-message; never sets aria-invalid and never blocks submission. error wins when both are set. |
size | size | 'small' | 'medium' | 'large' | 'medium' | The size of the text area: 'small', 'medium', or 'large'. |
label | label | string | '' | The label text displayed above the text area. |
value | value | string | '' | The current value of the text area. |
placeholder | placeholder | string | '' | Placeholder text displayed when the text area is empty. |
helperText | helper-text | string | '' | Helper text displayed below the text area to provide additional context. |
name | name | string | '' | The name attribute for form submission. |
autocomplete | autocomplete | string | '' | The autocomplete attribute for browser auto-completion. |
autofocus | autofocus | boolean | false | Marks this text area as the auto-focus target. Read by hy-dialog (and other overlay containers) on show to choose initial focus. Also focuses on first connect when used outside an overlay, mirroring native HTML autofocus but routed through JS so SSR'd HTML doesn't pull focus during hydration. |
autoselect | autoselect | boolean | false | After auto-focus lands, selects the current value so the user can type-to-replace. Pairs with autofocus for rename-style dialogs where the existing value is shown for context but is meant to be overwritten. |
errorMessage | error-message | string | '' | Error message shown under the text area (replaces the helper text). Setting it raises error, clearing it lowers it. |
warningMessage | warning-message | string | '' | Warning message shown under the text area (replaces the helper text). Setting it raises warning. |
maxlength | maxlength | number | undefined | — | Maximum number of characters allowed in the text area. |
minlength | minlength | number | undefined | — | Minimum number of characters required in the text area. |
rows | rows | number | 4 | Number of visible text lines in the text area. |
cols | cols | number | undefined | undefined | How many characters a line holds — the way to make a text area narrower than its container. One of 1–8, 10, 12, 16, 20, 24, 32, 48 (the set every field's character width shares). The textarea's content box is that many 0 glyphs in its own font (1ch plus the letter-spacing its size applies), plus its inline padding and border, so the same markup holds the same count in every design system; never wider than its container. A value outside the set is ignored — the text area fills its container, as it does without cols — and warned about in dev. Forwarded to the native <textarea> too. |
wrap | wrap | string | 'soft' | How text wraps in the text area: 'soft', 'hard', or 'off'. |
autoResize | auto-resize | boolean | false | Automatically adjusts height based on content when enabled. |
maxRows | max-rows | number | undefined | — | Caps auto-resize growth at this many text rows; past the cap the textarea scrolls internally instead of growing further. No effect unless auto-resize is set. When omitted, auto-resize grows unbounded. |
form | — | HTMLFormElement | null | — | — |
validity | — | ValidityState | — | — |
validationMessage | — | string | — | — |
Events
| Event | Detail | Description |
|---|---|---|
input | — | Fired when the text area value changes, includes current value |
change | — | Fired when the text area loses focus after a value change, includes current value |
focus | — | Fired when the text area receives focus |
blur | — | Fired when the text area loses focus |
CSS Parts
| Part | Description |
|---|---|
base | The text area's base wrapper element |
label | The label element |
container | The text area container element |
textarea | The native textarea element |
helper-text | The helper text element |
error-message | The error message element |
warning-message | The warning message element |
message-icon | The icon starting the error or warning message |
CSS Custom Properties
The documented hooks. Every override hook the component reads — one per token it paints — is listed in @whitespaceux/harmony/theme-api.json, and @whitespaceux/harmony/component-bindings.json (the Harmony MCP get-bindings tool) says which part and state each one paints.
| Property | Default | Description |
|---|---|---|
--hy-text-area-background-surface-base | var(--hy-background-surface-base) | Background color |
--hy-text-area-border-subtle-rest | var(--hy-border-subtle-rest) | Border color at rest |
--hy-text-area-border-brand-rest | var(--hy-border-brand-rest) | Focused edge color, any focus method. |
--hy-text-area-border-default-hover | var(--hy-border-default-hover) | Border color on hover |
--hy-text-area-border-danger-rest | var(--hy-border-danger-rest) | Border color in error state |
--hy-text-area-border-warning-rest | var(--hy-border-warning-rest) | Border color in warning state (at rest; any focus keeps the normal focus edge) |
--hy-text-area-foreground-warning-rest | var(--hy-foreground-warning-rest) | Warning message text and icon color |
--hy-text-area-gap-layout-2xs | var(--hy-gap-layout-2xs) | Gap between the message icon and its text |
--hy-text-area-stroke-sm | var(--hy-stroke-sm) | Border width |
--hy-text-area-radius-form-md | var(--hy-radius-form-md) | Border radius |
--hy-text-area-padding-layout-lg | var(--hy-padding-layout-lg) | Horizontal padding |
--hy-text-area-control-height-sm | var(--hy-control-height-sm) | 1-row control height at small size. |
--hy-text-area-control-height-md | var(--hy-control-height-md) | 1-row control height at medium size. |
--hy-text-area-control-height-lg | var(--hy-control-height-lg) | 1-row control height at large size. |
--hy-text-area-padding-vertical-sm | — | Vertical padding at small size. Default derives from the control height so one row lands on the contract |
--hy-text-area-padding-vertical-md | — | Vertical padding at medium size. Default derives from the control height so one row lands on the contract |
--hy-text-area-padding-vertical-lg | — | Vertical padding at large size. Default derives from the control height so one row lands on the contract |
--hy-text-area-gap-form-lg | var(--hy-gap-form-lg) | Gap between label and textarea |
--hy-text-area-min-height-sm | — | Minimum height for small size. Default: one contract row (the control height minus borders) |
--hy-text-area-min-height-md | — | Minimum height for medium size. Default: one contract row (the control height minus borders) |
--hy-text-area-min-height-lg | — | Minimum height for large size. Default: one contract row (the control height minus borders) |
Methods
focus()
Sets focus on the text area.
blur()
Removes focus from the text area.
select()
Selects all text in the text area.