Textarea

A textarea lets people enter free text that can be longer than a single line: the description of an automation, a label, or a calendar event, or a message to send to a voice assistant.

Use a textarea for:

• Free text that can run over several lines, like a description, notes, or a message

Don't use a textarea for:

• A short, single line value, like a name. Use a text input.
• Code or YAML. The frontend has a dedicated code editor for that.

1. Container: the filled field, with a line at the bottom
2. Label: names the text. It sits inside the field, and moves up when the field has focus or a value.
3. Text: the native textarea where people type
4. Hint: optional help text below the field, replaced by the validation message when the text is invalid

Most textareas in the frontend grow with their content: the field starts small, grows while people type, and starts scrolling when it reaches its maximum height (200 pixels by default). That keeps a short text compact, without hiding a long one.

A textarea that does not grow has a fixed height, in rows of text (4 by default). Use that when you know roughly how much text to expect, and want the space to be there from the start.

Use the hint for anything that helps people write the text, like whether formatting is supported.

• Empty: the label sits inside the field, at the size of the text.
• Hover: the field changes to the hover background.
• Focus: the line at the bottom gets thicker and turns the primary color, and so does the label.
• Filled: once the field has a value or focus, the label moves up and gets smaller. With a placeholder, the label is always up. The label has the background of the field, so text that scrolls stays readable under it.
• Required: the label gets a * marker. The field must have text for the form to be valid.
• Disabled: the field gets the disabled background and is dimmed to half its opacity, and the text can't be changed or focused.
• Read-only: shows text that people can read and copy, but not change.
• Invalid: the label and the line at the bottom turn to the danger color, and the validation message takes the place of the hint. A field becomes invalid when the code marks it invalid, when a form check finds the text invalid, or, for a field that checks itself, when it loses focus. It turns valid again as soon as people type valid text.

The text uses --ha-font-family-body. Changes in color, line, and label position take 150ms.

• Keep labels short: Description, Notes, Message.

Key presses in the textarea don't trigger keyboard shortcuts around it.

Focus shows as the primary color on the line at the bottom and on the label, instead of a separate focus ring.

The field is at least 56px high, and as wide as its container.

A screen reader announces the textarea with its label, and reads the hint as its description. When the field turns invalid, the validation message is announced. Required, disabled, and read only are announced as well. Without a label, only the placeholder describes it, so always give it a label.

• Focus goes to the native textarea inside the component.

• The component stops keydown events from leaving it.

• The label is a native <label> connected to the textarea, so it is the accessible name.

• Without a label, the <label> is empty and hidden from assistive technology. The placeholder is then the only text that describes the textarea.

• The hint and the validation message are connected to the textarea with aria-describedby, so screen readers read them as the description.

• The validation message is in a live region, and gets the role alert while the field is invalid, so screen readers announce it when it appears.

• Required, disabled, and read-only are set on the native textarea, so assistive technology gets them as is.

• Text input: a single line of text
• Form: builds fields from a schema
• Selector: the text selector with multiline shows a textarea
• UI text: how to write labels, hints, and errors

The element is <ha-textarea>. It is based on the Web Awesome textarea.

<ha-textarea label="Description" resize="auto"></ha-textarea>
<ha-textarea label="Message" rows="6"></ha-textarea>
<ha-textarea label="Notes" hint="Supports Markdown." required></ha-textarea>

• label: the label.
• value: the current value.
• hint: help text below the textarea.
• placeholder: text shown while the textarea is empty.
• rows: the number of visible lines. Defaults to 4.
• resize: none (default), vertical, horizontal, both, or auto. With auto, the textarea grows with its content, up to --ha-textarea-max-height.
• required: makes the field required, and adds a marker after the label.
• disabled: disables the textarea.
• readonly: makes the textarea read-only.
• invalid: marks the textarea as invalid.
• validation-message: the message shown when the textarea is invalid. Without it, the browser's own message is shown.
• auto-validate: validates the textarea when it loses focus, instead of waiting for the form to be submitted.
• minlength and maxlength: the minimum and maximum length of the value.
• name, autocomplete, autocapitalize, autofocus, spellcheck, inputmode, and enterkeyhint: passed to the native textarea, and work the same as on a regular <textarea>.

The maximum height for resize="auto" only applies when resize is set as an attribute. The property does not reflect, so setting only .resize from code gives you a textarea that grows without limit.

• label: a label with markup. Content in this slot replaces the text of the label attribute, including the required marker.
• hint: a hint with markup, like a link. Only used when the hint attribute is not set.

• input: fires on every change to the value, while people type.
• change: fires when the value is committed, like when the textarea loses focus.

Read the new value from value on the element. Key presses do not bubble out of the textarea: it stops keydown events, so typing, or pressing Enter for a new line, does not trigger keyboard handlers around it.

• --ha-textarea-max-height: the maximum height with resize="auto". Defaults to 200px.
• --ha-textarea-padding-bottom: the space below the textarea.
• --ha-textarea-required-marker: the marker after the label of a required field. Defaults to "*".

Source: src/components/ha-textarea.ts