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.
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="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. |
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 displayed when the text area is in an invalid state. |
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 | — | Number of visible character columns in the text area. |
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 |
CSS Custom Properties
| Property | Description |
|---|---|
--hy-text-area-background-rest | Background color |
--hy-text-area-border-rest | Border color at rest |
--hy-text-area-border-active | Focused edge color, any focus method. Default: var(--hy-border-brand-rest) |
--hy-text-area-border-hover | Border color on hover |
--hy-text-area-border-danger | Border color in error state |
--hy-text-area-stroke | Border width |
--hy-text-area-radius | Border radius |
--hy-text-area-padding-horizontal | Horizontal padding |
--hy-text-area-height-sm | 1-row control height at small size. Default: var(--hy-control-height-sm) |
--hy-text-area-height-md | 1-row control height at medium size. Default: var(--hy-control-height-md) |
--hy-text-area-height-lg | 1-row control height at large size. Default: var(--hy-control-height-lg) |
--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 | Gap between label and textarea |
--hy-text-area-font-family | Font family override for the textarea value text |
--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.