A multi-line text field with a label, helper text, and error, warning, and read-only states.
Live example
These are real Text area blocks rendering on this page right now. Tab to them and try them in both color schemes.
Up to 200 characters.
Cannot be empty.
Looks unusual.
Dark mode you don’t have to build
Every block supports dark mode. Use the light/dark toggle in the header and the live example above switches with it.
Parameters
Everything the Text area block accepts. Setting is the label you see in the block’s settings panel. Parameter is what the same value is called in code. Accepts is what you can put in it.
| Setting | Parameter | Type | Default | Accepts | What it does |
|---|---|---|---|---|---|
| Typed on the block | label | string | “Description” | Any text | The visible label. Screen readers announce it too, so make it say what the control does. |
| Name | name | string | empty | Any text | The field name submitted with the form. |
| Placeholder | placeholder | string | empty | Any text | Ghost text inside the empty field. Never use it instead of a label. |
| Default value | value | string | empty | Any text | Pre-filled content. |
| Rows | rows | number | 4 | A number | The visible height, in lines. |
| Columns (0 = auto) | cols | number | 0 | A number | The visible width, in characters. |
| Helper text | helperText | string | empty | Any text | A short hint under the control, linked to it for screen readers. |
| Invalid | invalid | boolean | false | true or false | Renders the error state. |
| Invalid message | invalidText | string | empty | Any text | The error message. It is announced to screen readers, not just colored red. |
| Warning | warn | boolean | false | true or false | Renders the warning state: something needs attention but does not block submission. |
| Warning message | warnText | string | empty | Any text | The warning message shown and announced in the warning state. |
| Disabled | disabled | boolean | false | true or false | Renders the disabled state. Disabled controls are skipped by keyboard focus, so prefer hiding over disabling when you can. |
| Read-only | readonly | boolean | false | true or false | Makes the field read-only: visible and focusable, but not editable. |
| Required | required | boolean | false | true or false | Marks the field as required, in the markup and for screen readers. Following Carbon, a required field shows no mark: when most fields in a form are required, add (optional) to the labels of the others. |
| Max length | maxlength | number | 0 | A number | The maximum number of characters accepted. |
| Visually hide label | hideLabel | boolean | false | true or false | Visually hides the label while keeping it for screen readers. Use only when the context makes the purpose obvious. |
| Carbon default | carbonDefault | boolean | false | true or false | Uses Carbon’s own field look (a shaded fill with one line under the text) instead of AWT’s default border on all four sides. |
Accessibility parameters, on this and every AWT block
Every AWT block has an Accessibility panel in its settings. Each control in it becomes a real HTML attribute on the block’s outer element:
| Setting | Parameter | What it does |
|---|---|---|
| Accessible name (aria-label) | ariaLabel | Becomes aria-label on the block’s outer element. Replaces the accessible name screen readers announce. Set it only when the visible label is not enough. |
| Described by (aria-describedby) | ariaDescribedby | Becomes aria-describedby. Point it at the ID of another element on the page whose text adds a longer description. |
| Labelled by (aria-labelledby) | ariaLabelledby | Becomes aria-labelledby. Point it at the ID of another element whose text should become this block’s accessible name. |
| Role | awtRole | Becomes the role attribute. Overrides the element’s ARIA role. The list offers only roles that suit the element. |
| Language (lang) | awtLang | Becomes the lang attribute. Set it when this block’s content is in a different language from the page, as a BCP-47 code like “fr”. |