---
schema_version: "1"
id: ead8363482de54d549424ce0b58ac61193a3d8718e78fbf8ae89bdc0a95d4187
title: Textarea
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/textarea/lightning-textarea.md
canonical_url: https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-textarea.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: ba61e2ba0f3fa09ca9d331b4ec4058cc60a24b13c3b2a668129c74ab2d147e6a
products:
  - Lightning Component Reference
---

# Textarea

**`lightning-textarea`**

Represents a multiline text input field.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="textarea" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-textarea` component creates an HTML `textarea` element for
entering multi-line text input. A text area holds an unlimited number of
characters.

To set the input for the text area, specify its value using the `value` attribute. Setting this value overwrites any initial value that's provided.

This example creates a text area with a maximum length of 300 characters.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-textarea
        value="initial value"
        label="What are you thinking about?"
        max-length="300"
    >
    </lightning-textarea>
</template>
```
<!-- prettier-ignore-end -->

## Design

`lightning-textarea` implements the textarea blueprint in the Salesforce Lightning Design System (SLDS). The textarea adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Textarea](https://v1.lightningdesignsystem.com/components/textarea/)                                                                 | [Textarea](https://www.lightningdesignsystem.com/components/textarea/)                                          |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Usage

In many browsers, the text area is resizable by default, and a vertical scrollbar is displayed when the content exceeds the number of rows. Consider these limitations:

- Specifying the `rows` and `cols` attributes isn't supported.
- Specifying the CSS width and height properties isn't supported.

You can define a function in JavaScript to handle input events like
`blur`, `focus`, and `change`. For example, to handle a `change` event on
the component, use the `onchange` attribute.

To retrieve the content of the text area field, use `event.detail.value` property.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-textarea
        name="myTextArea"
        value="initial value"
        label="What are you thinking about?"
        onchange={countLength}
    >
    </lightning-textarea>
</template>
```
<!-- prettier-ignore-end -->

## Input Validation

Client-side input validation is available for this component. Set a maximum
length using the `maxlength` attribute or a minimum length using the
`minlength` attribute. An error message is automatically displayed in these cases:

- A required field is empty when `required` is present on the `lightning-textarea` tag.
- The input value contains fewer characters than that specified by the `minlength` attribute.
- The input value contains more characters than that specified by the `maxlength` attribute.

To check the validity states of an input, use the `validity` attribute, which
is based on the `ValidityState` object. You can access the validity states in
your JavaScript. This `validity` attribute returns an object with
`boolean` properties. For more information, see the
[`lightning-input`](/docs/platform/lightning-component-reference/guide/lightning-input.html) documentation.

You can override the default message by providing your own values for
`message-when-value-missing`, `message-when-bad-input`, `message-when-too-long`, or
`message-when-too-short`.

For example, provide an error message when a required field's value is missing.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-textarea
        name="myText"
        label="Your Name"
        message-when-value-missing="This field is required."
        required
    >
    </lightning-textarea>
</template>
```
<!-- prettier-ignore-end -->

## Insert Text Programmatically

You can insert text programmatically in the text area with the `setRangeText()` method, replacing content
or inserting new content.

The `setRangeText()` method follows the API of the standard `HTMLInputElement.setRangeText()` method described on
[MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setRangeText).

`setRangeText()` supports these parameters.

| Parameter   | Type   | Description                                                   |
| ----------- | ------ | ------------------------------------------------------------- |
| replacement | string | The string to insert.                                         |
| start       | number | The 0-based index of the first character to replace.          |
| end         | number | The 0-based index that follows the last character to replace. |
| selectMode  | string | Defines how the selection is set after the text is inserted.  |

Valid values for selectMode are:

- `select` - Selects the inserted text. The text area must have focus when `setRangeText()` is called.
- `start` - Moves the selection to just before the inserted text.
- `end` - Moves the selection to just after the inserted text.
- `preserve` - Attempts to preserve the selection in effect before the insertion. This is the default.

To insert replacement text at the current cursor location, specify only the
replacement string and no other parameters. After the insertion, the cursor
remains in the original location. If text is selected when the insertion occurs,
the text is replaced.

This example uses `setRangeText()` to insert some text at the beginning of the line
without replacing any content.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-textarea placeholder="Type something interesting">
    </lightning-textarea>
    <lightning-button label="Insert Text" onclick={handleClick}>
    </lightning-button>
</template>
```
<!-- prettier-ignore-end -->

Setting the start and end values to 0 begins the insertion with the character at
index 0, but ends at the character before index 0. The result is that no characters are
replaced, and the text is inserted in front of the character at index 0.

The selectMode value `select` causes the inserted content to be selected. Call the `focus()`
method before `setRangeText()` to enable the selection.

```javascript
import { LightningElement } from "lwc";

export default class SetRangeTextExample extends LightningElement {
  start = 0;
  end = 0;
  selectMode = "select";

  handleClick() {
    const textarea = this.template.querySelector("lightning-textarea");
    textarea.focus();
    textarea.setRangeText("Some new text", this.start, this.end, this.selectMode);
  }
}
```

This example inserts a space at index 10 and removes characters at index 10 through 14.
The resulting content of the text area is `0123456789 567890`.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-textarea value="012345678901234567890"> </lightning-textarea>
    <lightning-button label="Clip Text" onclick={handleClick}>
    </lightning-button>
</template>
```
<!-- prettier-ignore-end -->

You can omit the final parameter of `setRangeText()` to use the default select mode, `preserve`.

```javascript
import { LightningElement } from "lwc";

export default class SetRangeTextExample extends LightningElement {
  handleClick() {
    const textarea = this.template.querySelector("lightning-textarea");
    textarea.setRangeText(" ", 10, 15);
  }
}
```

These examples describe the insertion behavior with various `setRangeText()`parameter values.

```javascript
// Insert text at cursor position. Replace any selected text.
textarea.setRangeText("Some new text");

// Insert text to replace characters beginning at index 10 (the 11th
// character) and ending at index 15 (the 16th character). The character
// at index 14 is the last character replaced.
// No selectMode is specified, so the original selection is preserved.
textarea.setRangeText("Some new text", 10, 15);

// Set focus on the text area.
// Insert text as described in the previous example, and then select
// the new text.
textarea.focus();
textarea.setRangeText("Some new text", 10, 15, "select");

// Insert text as described, and place cursor ahead of the new text.
textarea.setRangeText("Some new text", 10, 15, "start");

// Insert text as described, and place cursor after the new text.
textarea.setRangeText("Some new text", 10, 15, "end");

// Insert text as described, and return to the previous selection state.
textarea.setRangeText("Some new text", 10, 15, "preserve");
```

If text is selected when selectMode is `preserve` and start and end values are specified,
the text insertion has no effect on the selected text. The text remains selected and is not replaced.

## Autocomplete Support

Textarea fields can be autofilled, based on your browser's support of the feature.
The `autocomplete` attribute passes through its value to the browser.

See [MDN web docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete) for more information.

## Component Styling

Use a combination of variants and utility classes to customize your textarea field.

### Variants

Specify the `variant` attribute with one of these values.

- `standard` is the default variant, which shows the text label above the textarea field
- `label-hidden` hides the text label from view, but makes it available to assistive technology
- `label-inline` horizontally aligns the text label and textarea field
- `label-stacked` places the label above the textarea field

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

This example adds padding on top of the textarea using an SLDS class.

<!-- prettier-ignore-start -->
```html
<lightning-textarea class="slds-p-top_small" label="Enter comments">
</lightning-textarea>
```
<!-- prettier-ignore-end -->

### Styling Hooks

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component styling hooks.

For more information, see [Style Components Using Lightning Design System Styling Hooks](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-custom-properties) in the Lightning Web Components Developer Guide.


## Usage Considerations

`lightning-textarea` determines the width of the field using the container's layout. Providing your own width on the component isn't recommended as the component is then no longer responsive to the change on the container's layout, such as when the browser is resized.

End users can resize the text area vertically by default on browsers that support it. You can't disable resizing using the `resize` CSS property. End users can't resize read-only text area fields.

To prevent users from resizing the field more than a specific width or height, pass in your custom class using the `class` attribute with the `max-width` and `max-height` CSS properties. Using these CSS properties on a read-only field isn't supported.

When working with `lightning-textarea`, consider these usage guidelines.

- Use `lightning-textarea` component with the `disabled` or `read-only` attribute, but not both simultaneously. Applying both `disabled` and `read-only` attributes to the component can result in unexpected behavior.
- When you specify `read-only`, the component displays with a bottom border only. The height of the component can't be changed. Using a styling hook to override the minimum height is also not supported for read-only text area fields. The component determines the height based on the amount of text content in `value`. Specify `read-only` if you want to prevent users from modifying the field, but still allow for interaction, which includes being able to tab into the field, place focus and set `.focus()`, and submit the field `value` with the form.
- When you specify `disabled`, the text area is grayed out, but you can adjust the height of the text area. Specify `disabled` to prevent users from interacting with the text area. In a disabled text area, you can't gain focus or set focus programmatically using `.focus()`. The disabled field value is excluded from form submission.
- The vertical scrollbar is displayed only when `lightning-textarea` is either `disabled` or editable, and when the content exceeds the text area's height. Scrollbars do not appear when `read-only` property is applied, as height is determined by the amount of text content in `value`.

## Accessibility

Use the `label` attribute to identify the text area for users of assistive technology.
The `label` attribute creates an HTML label element on the input element. To hide a
label from view and make it available to assistive technology, use the `label-hidden` variant.

When the character count provided by `maxlength` is reached, the component renders an error message
as assistive text with `role="alert"`, which notifies users of assistive technologies that the limit is reached.


:::::

:::::tab
::component-specification{component="textarea" model="lwc" namespace="lightning"}

:::::

::::::