Textarea

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.

1<template>
2    <lightning-textarea
3        value="initial value"
4        label="What are you thinking about?"
5        max-length="300"
6    >
7    </lightning-textarea>
8</template>

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.

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.

1<template>
2    <lightning-textarea
3        name="myTextArea"
4        value="initial value"
5        label="What are you thinking about?"
6        onchange={countLength}
7    >
8    </lightning-textarea>
9</template>

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 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.

1<template>
2    <lightning-textarea
3        name="myText"
4        label="Your Name"
5        message-when-value-missing="This field is required."
6        required
7    >
8    </lightning-textarea>
9</template>

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.

setRangeText() supports these parameters.

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.

1<template>
2    <lightning-textarea placeholder="Type something interesting">
3    </lightning-textarea>
4    <lightning-button label="Insert Text" onclick={handleClick}>
5    </lightning-button>
6</template>

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.

1import { LightningElement } from "lwc";
2
3export default class SetRangeTextExample extends LightningElement {
4  start = 0;
5  end = 0;
6  selectMode = "select";
7
8  handleClick() {
9    const textarea = this.template.querySelector("lightning-textarea");
10    textarea.focus();
11    textarea.setRangeText("Some new text", this.start, this.end, this.selectMode);
12  }
13}

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.

1<template>
2    <lightning-textarea value="012345678901234567890"> </lightning-textarea>
3    <lightning-button label="Clip Text" onclick={handleClick}>
4    </lightning-button>
5</template>

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

1import { LightningElement } from "lwc";
2
3export default class SetRangeTextExample extends LightningElement {
4  handleClick() {
5    const textarea = this.template.querySelector("lightning-textarea");
6    textarea.setRangeText(" ", 10, 15);
7  }
8}

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

1// Insert text at cursor position. Replace any selected text.
2textarea.setRangeText("Some new text");
3
4// Insert text to replace characters beginning at index 10 (the 11th
5// character) and ending at index 15 (the 16th character). The character
6// at index 14 is the last character replaced.
7// No selectMode is specified, so the original selection is preserved.
8textarea.setRangeText("Some new text", 10, 15);
9
10// Set focus on the text area.
11// Insert text as described in the previous example, and then select
12// the new text.
13textarea.focus();
14textarea.setRangeText("Some new text", 10, 15, "select");
15
16// Insert text as described, and place cursor ahead of the new text.
17textarea.setRangeText("Some new text", 10, 15, "start");
18
19// Insert text as described, and place cursor after the new text.
20textarea.setRangeText("Some new text", 10, 15, "end");
21
22// Insert text as described, and return to the previous selection state.
23textarea.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.

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 for more information.

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

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

To apply additional styling, use the SLDS utility classes with the class attribute.

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

1<lightning-textarea class="slds-p-top_small" label="Enter comments">
2</lightning-textarea>

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 for available component styling hooks.

For more information, see Style Components Using Lightning Design System Styling Hooks in the Lightning Web Components Developer Guide.

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.

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.