Text Area is a multiple line text input control.
Overview
Text Area allows users to enter a sizeable amount of free form text.
Sample
Usage
- Collect user inputs like comments or reviews in forms
Accessibility
Keyboard navigation
| Key | Function |
|---|---|
Tab | Moves focus to the next focusable element. If the currently focused element is the last element, focus will leave the component. |
Tab and Shift | Moves focus to the previous focusable element. If the currently focused element is the first element, focus will leave the component. |
API reference
Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
| columns | columns | Specifies the component's number of columns. | number | |
| disabled | disabled | When true, interaction is prevented and the component is displayed with lower opacity. | boolean | false |
| form | form | Specifies the id of the component's associated form.
When not set, the component is associated with its ancestor form element, if one exists. | string | |
| groupSeparator | group-separator | When true, number values are displayed with a group separator corresponding to the language and country format. | boolean | false |
| label | label | Specifies an accessible label for the component. | string | |
| labelText | label-text | Specifies the component's label text. | string | |
| limitText | limit-text | When true, prevents input beyond the maxLength value, mimicking native text area behavior. | boolean | false |
| loading | loading | When true, a busy indicator is displayed. | boolean | false |
| maxLength | max-length | When the component resides in a form, specifies the maximum number of characters allowed. | number | |
| messageOverrides | Overrides individual strings used by the component. | Record<string, unknown> | undefined | ||
| minLength | min-length | When the component resides in a form, specifies the minimum number of characters allowed. | number | |
| name | name | Specifies the name of the component. Required to pass the component's value on form submission. | string | |
| numberingSystem | numbering-system | Specifies the Unicode numeral system used by the component for localization. | NumberingSystem | |
| placeholder | placeholder | Specifies the placeholder text for the component. | string | |
| readOnly | read-only | When true, the component's value can be read, but cannot be modified. | boolean | false |
| required | required | When true and the component resides in a form,
the component must have a value in order for the form to submit. | boolean | false |
| resize | resize | Specifies if the component is resizable. | "both" | "horizontal" | "vertical" | "none" | "both" |
| rows | rows | Specifies the component's number of rows. | number | |
| scale | scale | Specifies the size of the component. | "l" | "m" | "s" | "m" |
| status | status | Specifies the status of the input field, which determines message and icons. | Status | "idle" |
| validationIcon | validation-icon | Specifies the validation icon to display under the component. | IconName | boolean | |
| validationMessage | validation-message | Specifies the validation message to display under the component. | string | |
| validity | The component's current validation state. | MutableValidityState | ||
| value | value | The component's value. | string | "" |
| wrap | wrap | Specifies the wrapping mechanism for the text. | "soft" | "hard" | "soft" |
Slots
| Name | Description |
|---|---|
| default (unnamed) | A slot for adding text. |
| label-content | A slot for rendering content next to the component's labelText. |
| footer-start | A slot for adding content to the start of the component's footer. |
| footer-end | A slot for adding content to the end of the component's footer. |
Styles
| Name | Description |
|---|---|
| --calcite-text-area-background-color | Specifies the component's background color. |
| --calcite-text-area-border-color | Specifies the component's text area border color. |
| --calcite-text-area-character-limit-text-color | Specifies the color of the character limit text displayed in the footer of the component. |
| --calcite-text-area-divider-color | Specifies the color of the divider between the text area and footer. |
| --calcite-text-area-font-size | Specifies the font size of the text area and footer. |
| --calcite-text-area-max-height | Specifies the component's text area maximum height. |
| --calcite-text-area-min-height | Specifies the component's text area minimum height. |
| --calcite-text-area-max-width | Specifies the component's text area maximum width. |
| --calcite-text-area-min-width | Specifies the component's text area minimum width. |
| --calcite-text-area-text-color | Specifies the component's text color. |
| --calcite-text-area-footer-border-color | Specifies the footer's border color. |
| --calcite-text-area-corner-radius | Specifies component's corner radius. |
| --calcite-text-area-shadow | Specifies the component's shadow. |
| --calcite-text-area-footer-background-color | Specifies the footer's background color. |
Events
| Name | Description | Behavior |
|---|---|---|
| calciteTextAreaChange | Fires each time a new value is typed and committed. | |
| calciteTextAreaInput | Fires each time a new value is typed. |
Methods
| Name | Description | Signature |
|---|---|---|
| componentOnReady | Create a promise that resolves once component is fully loaded. | componentOnReady(): Promise<this> |
| selectText | Selects the text of the component's value. | selectText(): Promise<void> |
| setFocus | Sets focus on the component. | setFocus(options?: FocusOptions): Promise<void> |