Textarea

A lightning:textarea component creates an HTML textarea element for entering multiline text input. A textarea field holds an unlimited number of characters.

This component implements styling from textarea in the Lightning Design System.

The following example creates a textarea field 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 client-side controller action to handle input events like blur, focus, and change. For example, to handle a change event on the component, use the onchange attribute.

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. You can make the textarea field a required field by setting required="true". Note that a disabled textarea field is always valid. An error message is automatically displayed in the following cases:

• A required field is empty when required is set to true.
• 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 client-side controller. This validity attribute returns an object with boolean properties.

You can override the default message by providing your own values for messageWhenValueMissing, messageWhenBadInput, messageWhenTooLong, or messageWhenTooShort.

This example displays a custom message when a required textarea field is empty.

To programmatically display error messages on invalid fields, use the reportValidity() method. For custom validity error messages, display the message using setCustomValidity() and reportValidity(). For more information, see the lightning:input documentation.

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 is responsive to the viewport size. The component dynamically determines the width of the field using the container's layout, so providing a specific width on the component isn't recommended. When the component has a static width, it's no longer responsive to the change on the container's layout, such as when the browser is resized.

Users can't resize read-only text area fields. However, users can resize editable text area fields vertically by default on browsers that support it. You can't prevent users from resizing the text area with the resize CSS property.

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 readonly attribute, but not both simultaneously. Applying both disabled and readonly attributes to the component can result in unexpected behavior.
• When you specify readonly, 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 readonly 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 readonly property is applied, as height is determined by the amount of text content in value.

You must provide a text label for accessibility to make the information available to assistive technology. The label attribute creates an HTML label element for your input component. 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.