;
};
A textarea is a multi-line text input control. Use it when users need to provide longer pieces of text such as comments, messages, or descriptions where a single-line input would be too limiting.
Use an [Input](/components/input) when users only need to enter a short, single-line value. Use a Textarea when the expected content spans multiple lines.
## When to use
Use a textarea when
* Users need to enter multiple lines of text such as a comment, review, or description
* The expected input length varies and may be long
* Free-form text entry is required without a predefined set of values
* Context makes the textarea purpose clear through a visible label
Do not use a textarea when
* The expected input is a short single-line value — use an Input instead
* Users must choose from a fixed set of options — use a Select or Radio
* The field value is meant to be read-only in the final UI — use plain text
* Rich formatting or markdown editing is required — consider a dedicated editor
## Anatomy
The textarea is composed of a label area, an input container, and an optional helper area. Each part can carry additional icons and text to guide users through data entry.
| Part | Element | Description |
| ------ | ----------------- | -------------------------------------------------------------------- |
| **1** | Optional label | Secondary descriptive text displayed alongside the main label |
| **2** | Text | The value or placeholder text inside the control |
| **3** | Label icon | Optional icon displayed next to the label |
| **4** | Label | The primary field label rendered via the `label` slot |
| **5** | Leading icon | Optional icon displayed at the start of the input container |
| **6** | Container | The outer border and background wrapper of the textarea |
| **7** | Validation icon | Icon shown when `validation-status` is set (error, warning, success) |
| **8** | Helper text | Optional guidance or error text rendered via the `helper-text` slot |
| **9** | Character counter | Shown automatically when `maxlength` is set |
| **10** | Trailing icon | Optional icon displayed at the end of the input container |
## Design guidelines
### States
A textarea supports five interactive states: **default**, **focused**, **disabled**, **read-only**, and **validation** (error, warning, success). The focused state shows a colored ring. The disabled state dims the control and blocks all interaction. The read-only state displays the value but prevents editing.
Always pair a textarea with a visible `label` slot. An unlabeled textarea has no accessible name and is inaccessible by default.
### Resize behavior
By default, users can drag the bottom-right corner to resize the textarea vertically. Set `disable-resize` to prevent resizing — useful when you want to maintain a consistent layout height. Alternatively, set `auto-grow` to let the textarea expand automatically as the user types, eliminating the need for manual resizing.
### Character counter
When `maxlength` is set to a value greater than zero, a character counter appears in the helper area below the textarea. It shows the current character count against the limit and helps users stay within bounds. The counter truncates input automatically when the limit is reached.
### Validation
Set `validation-status` to `error`, `warning`, or `success` to communicate the state of the field. Pair each state with a descriptive `helper-text` message so users know what went wrong and how to fix it. Use `error` for critical blocking issues, `warning` for non-blocking concerns, and `success` to confirm valid input.
## Usage
### Default
Use the default textarea when you need a standard multi-line text input. Provide a `label` slot for the field name and a `helper-text` slot for any additional guidance.
span {
display: flex;
align-items: center;
gap: var(--bq-spacing-xs);
}
Helper text
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
Helper text
```
```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqIcon, BqTextarea } from "@beeq/react";
export default () => (
Helper text
);
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqIcon, BqTextarea } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqIcon, BqTextarea],
template: `
Helper text
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Helper text
```
### Initial value
Pre-populate your textarea with an initial `value` attribute to streamline user interactions and provide a helpful starting point.
span {
display: flex;
align-items: center;
gap: var(--bq-spacing-xs);
}
Helper text
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Helper text
```
```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqIcon, BqTextarea } from "@beeq/react";
export default () => (
Helper text
);
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqIcon, BqTextarea } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqIcon, BqTextarea],
template: `
Helper text
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Helper text
```
## Options
### Disabled
Set `disabled` when the field is not currently available for interaction. Use it to present non-editable content in a form context. Always communicate why the field is disabled through surrounding text or a tooltip.
span {
display: flex;
align-items: center;
gap: var(--bq-spacing-xs);
}
Helper text
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Helper text
```
```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqIcon, BqTextarea } from "@beeq/react";
export default () => (
Helper text
);
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqIcon, BqTextarea } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqIcon, BqTextarea],
template: `
Helper text
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Helper text
```
### Disable resize
Add `disable-resize` to prevent users from resizing the textarea. This is useful when you need a stable layout with a consistent textarea height.
.textarea--resize-group {
display: grid;
grid-template-columns: repeat(2, minmax(0px, 1fr));
gap: var(--bq-spacing-m);
}
span {
display: flex;
align-items: center;
gap: var(--bq-spacing-xs);
}
Helper text
Helper text
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
Maintain a consistent layout by preventing users from resizing.
### Max length
Set `maxlength` to limit the number of characters users can enter. A character counter appears automatically below the textarea to show progress toward the limit. Input is truncated once the limit is reached.
span {
display: flex;
align-items: center;
gap: var(--bq-spacing-xs);
}
Helper text
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Helper text
```
```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqIcon, BqTextarea } from "@beeq/react";
export default () => (
Helper text
);
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqIcon, BqTextarea } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqIcon, BqTextarea],
template: `
Helper text
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Helper text
```
### Read only
Set `readonly` to display the value without allowing edits. Unlike `disabled`, a read-only textarea is still focusable and its value is submitted with the form.
span {
display: flex;
align-items: center;
gap: var(--bq-spacing-xs);
}
Helper text
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Helper text
```
```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqIcon, BqTextarea } from "@beeq/react";
export default () => (
Helper text
);
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqIcon, BqTextarea } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqIcon, BqTextarea],
template: `
Helper text
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Helper text
```
### Validation
Set `validation-status` to `error`, `warning`, or `success` to communicate the state of the field. Always pair a validation status with a descriptive `helper-text` message so users understand the issue and how to resolve it.
.textarea--validation-group {
display: grid;
grid-template-columns: repeat(3, minmax(0px, 1fr));
gap: var(--bq-spacing-m);
}
span {
display: flex;
align-items: center;
gap: var(--bq-spacing-xs);
}
Helper text
Helper text
Helper text
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Helper text
Helper text
Helper text
```
```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqIcon, BqTextarea } from "@beeq/react";
export default () => (
<>
Helper text
Helper text
Helper text
);
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqIcon, BqTextarea } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqIcon, BqTextarea],
template: `
```
Use validation feedback to provide context on the textarea's status based on user input.
### Form integration
`bq-textarea` submits its current text value with the form. Use `required` and `form-validation-message` when users must provide multiline feedback before submitting.
body {
padding: var(--bq-spacing-l);
}
.textarea-form {
display: grid;
gap: var(--bq-spacing-m);
}
.textarea-form__actions {
display: flex;
gap: var(--bq-spacing-s);
justify-content: flex-end;
}
.textarea-form__output {
margin: 0;
padding: var(--bq-spacing-s);
border: var(--bq-stroke-s) solid var(--bq-stroke--tertiary);
border-radius: var(--bq-radius--s);
background: var(--bq-ui--secondary);
color: var(--bq-text--primary);
white-space: pre-wrap;
}
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { useState } from "react";
import { BqButton, BqTextarea } from "@beeq/react";
export default function TextareaForm() {
const [data, setData] = useState("{}");
return (
);
}
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqButton, BqTextarea } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqButton, BqTextarea],
template: `
`,
})
export class TextareaFormComponent {
data = "{}";
handleSubmit(event: SubmitEvent): void {
event.preventDefault();
this.data = JSON.stringify(Object.fromEntries(new FormData(event.target as HTMLFormElement).entries()), null, 2);
}
}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
## Best practices
Do
Always provide a visible label via the `label` slot. An unlabeled textarea has no accessible name and relies entirely on context, which screen readers cannot infer.
Don't
Use placeholder text as a substitute for a label. Placeholder text disappears as soon as the user starts typing, leaving the field without any visible description.
Do
Write user-centric validation messages that explain what went wrong and how to fix it, not only that the input was invalid.
Don't
Show vague error messages like "Invalid input". Users need actionable guidance to correct their input, not a generic error label.
Do
Use `maxlength` for inputs where length matters — tweet-like comments, SMS text, or short descriptions. The character counter gives users clear progress feedback.
Don't
Set `maxlength` on open-ended fields like detailed feedback forms or long descriptions where an arbitrary limit would frustrate users.
Do
Use a textarea only when the expected input is long or variable in length. This sets the right expectation for users about how much text they should provide.
Don't
Use a textarea when a short single-line response is expected. An oversized input creates confusion and wastes space — use an Input component instead.
## Accessibility
`bq-textarea` renders a native `
A textarea is a multi-line text input control. Use it when users need to provide longer pieces of text such as comments, messages, or descriptions where a single-line input would be too limiting.
The textarea is composed of a label area, an input container, and an optional helper area. Each part can carry additional icons and text to guide users through data entry.
| Part | Element | Description |
| ------ | ----------------- | -------------------------------------------------------------------- |
| **1** | Optional label | Secondary descriptive text displayed alongside the main label |
| **2** | Text | The value or placeholder text inside the control |
| **3** | Label icon | Optional icon displayed next to the label |
| **4** | Label | The primary field label rendered via the `label` slot |
| **5** | Leading icon | Optional icon displayed at the start of the input container |
| **6** | Container | The outer border and background wrapper of the textarea |
| **7** | Validation icon | Icon shown when `validation-status` is set (error, warning, success) |
| **8** | Helper text | Optional guidance or error text rendered via the `helper-text` slot |
| **9** | Character counter | Shown automatically when `maxlength` is set |
| **10** | Trailing icon | Optional icon displayed at the end of the input container |
## Design guidelines
### States
A textarea supports five interactive states: **default**, **focused**, **disabled**, **read-only**, and **validation** (error, warning, success). The focused state shows a colored ring. The disabled state dims the control and blocks all interaction. The read-only state displays the value but prevents editing.