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.

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

The rows attribute and cols attribute are not supported. In many browsers, the text area is resizable by default, and a vertical scrollbar is displayed when the content exceeds the number of rows. Specifying the CSS width and height properties is not 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.

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

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.

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.

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.

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

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

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.

lightning-textarea implements the textarea blueprint in the Salesforce Lightning Design System (SLDS).

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.

Component styling hooks use the --slds-c-* prefix and change styling for specific elements or properties of a component. Component-specific styling isn’t recommended, because it’s unsupported for SLDS 2, but existing customizations still work with the original SLDS. If you use component styling hooks, limit the components to SLDS themes until SLDS 2 and the Salesforce Cosmos theme become generally available. See Styling Hooks Overview for documentation on component-specific hooks for this component.

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.