Text area

Text areas allow users to enter and edit multi-line text. They typically appear in forms.

Usage

Code

Accessibility

  <sl-text-area aria-label="Hobbies" value="Painting, drawing, dance..."></sl-text-area>

When to use

The following guidance describes when to use the text area component.

Unconstrained input

When you need to collect input that can be of variable length, such as comments, descriptions, or notes. Use a text area when the newline character (line break) is a valid part of the content.

When not to use

The following guidance describes when not to use the text area component.

If the input is expected to be short and concise, consider using a text field component instead of a Text Area. For instance, when collecting a username or password a single-line input is more appropriate.

Anatomy

Item	Name	Description	Optional
1	Input container	An interactive input area.	No
2	Input & placeholder text	Input text is a value the user has entered into an input and the placeholder text is a short hint that describes the expected value of an input.	No
3	Caret	A thin vertical line that blinks to indicate where input will be inserted.	No
4	Resize handle	An indicator that appears in the bottom right corner of the input container.	No

Figma Options

With these options, you can tweak the appearance of the text area in Figma. They are available in the Design Panel so you can compose the text area to exactly fit the user experience need for the use case you are working on.

Text Area

Item	Options	Description
Size	`md` `lg`	The text area come in two sized medium (default) and large.
State	`default` `valid` `invalid`	To indicate the state of the text area.
Filled	`boolean`	To indicate if the text area is filled or displays a placeholder.
Input text	`value`	To insert the text of the filled text or placeholder.

Label

Item	Options	Description
Label	`boolean`	To display a label.
Size	`sm` `md` `lg`	The label come in three sizes small, medium (default) and large.
Disabled	`boolean`	To show the disabled state of the label.
Required	`boolean`	Indicates if the text area is required.
Optional	`boolean`	Indicates if the text area is optional.
Info	`boolean`	To show a info icon with tooltip after the label.
Text	`value`	To insert the text of the label.

Hint

Item	Options	Description
Hint	`boolean`	To display the hint.
Size	`sm` `md` `lg`	The label come in three sizes small, medium (default) and large.
State	`default` `disabled` `invalid`	To indicate the state of the hint.
Icon	`boolean`	Displays an icon in front of the hint.
Text	`value`	To insert the text of the hint.

Focus ring

Item	Options	Description
Focus ring	`boolean`	To display the focus state of the text area.

  <sl-text-area aria-label="My favourite subject" value="My favourite subject is..."></sl-text-area>

API

Component has a range of properties to define the experience in different use cases.

Properties

Name	Attribute	Type	Default	Description
`autocomplete`	`autocomplete`	`typeof HTMLTextAreaElement.prototype.autocomplete \| undefined`		Specifies which type of data the browser can use to pre-fill the textarea. NOTE: Declare the type this way so it is backwards compatible with 4.9.5, which we still use in `@sl-design-system/angular`.
`customValidity`	`custom-validity`	`string \| undefined`		The error message to display when the control is invalid.
`dirty`	-	`boolean`	`false`	A control is dirty if the user has changed the value in the UI.
`disabled`	`disabled`	`boolean \| undefined`		Whether the textarea is disabled; when set no interaction is possible.
`form`	-	`HTMLFormElement \| null`		The form associated with the control.
`formValue`	-	`unknown`		The value used when submitting the form.
`labels`	-	`NodeListOf<HTMLLabelElement>` \| null		The labels associated with the control.
`maxLength`	`maxlength`	`number \| undefined`		Maximum length (number of characters).
`minLength`	`minlength`	`number \| undefined`		Minimum length (number of characters).
`name`	`name`	`string \| undefined`		The name of the form control.
`nativeFormValue`	-	`FormValue`		Returns the form value as used in a native `<form>`. This is always a string, File, FormData or null.
`placeholder`	`placeholder`	`string \| undefined`		Placeholder text in the input.
`readonly`	`readonly`	`boolean \| undefined`		Whether you can interact with the textarea or if it is just a static, readonly display.
`required`	`required`	`boolean \| undefined`		Whether the textarea is a required field.
`resize`	`resize`	`'none' \| 'vertical' \| 'auto'`	`'vertical'`	The way the textarea can be resized.
`rows`	`rows`	`number \| undefined`		The number of rows the textarea should initially have. If not set, the browser defaults to 2 rows.
`showValid`	`show-valid`	`boolean`	`false`	When set will cause the control to show it is valid after reportValidity is called.
`showValidity`	`show-validity`	`'valid' \| 'invalid' \| undefined`		Whether to show the validity state.
`size`	`size`	`'md' \| 'lg'`	`'md'`	The size of the textarea.
`textarea`	-	`HTMLTextAreaElement`		The textarea in the light DOM.
`touched`	-	`boolean`	`false`	A control is marked touched once the user has triggered a blur event on it.
`valid`	-	`boolean`		Returns whether the form control is valid or not.
`validationMessage`	-	`string`		String representing a localized (by the browser) message that describes the validation constraints that the control does not satisfy (if any). The string is empty if the control is not a candidate for constraint validation, or it satisfies its constraints. For true localization, see `getLocalizedValidationMessage()` instead.
`validity`	-	`ValidityState`		Returns the validity state the control is in.
`validityState`	-	`'valid' \| 'invalid' \| 'pending'`		Returns the current validity state.
`value`	`value`	`unknown \| undefined`	`''`	The value for the textarea.
`wrap`	`wrap`	`'soft' \| 'hard'`	`'soft'`	The way text should be wrapped during form submission.

Methods

Name	Parameters	Return	Description
`focus`		`void`
`getLocalizedValidationMessage`		`string`	This returns a localized validation message. It does not support all `ValidityState` properties, since some require more context than we have here. If you need to support more, you can override this method in your own form control.
`reportValidity`		`boolean`	Returns whether the control is valid. If the control is invalid, calling this will also cause an `invalid` event to be dispatched. After calling this, the control will also report the validity to the user.
`setCustomValidity`	`message: string \| Promise<string>`	`void`	Sets a custom validation message for the form control. If the message is not an empty string, that will make the control invalid. By setting it to an empty string again, you can make the control valid again.

Events

Name	Event type	Description
`sl-blur`	`SlBlurEvent`	Emits when the focus leaves the component.
`sl-change`	`SlChangeEvent<string>`	Emits when the value changes.
`sl-focus`	`SlFocusEvent`	Emits when the component gains focus.
`sl-form-control`	`SlFormControlEvent`	Emits when the form control is added to the DOM.
`sl-update-state`	`SlUpdateStateEvent`	Emits when the UI state (dirty, pristine, touched or untouched) of the form control changes.
`sl-update-validity`	`SlUpdateValidityEvent`	Emits when the validity of the form control changes.
`sl-validate`	`SlValidateEvent`	Emits when the form control can be validated.

Slots

Name	Description
`textarea`	The slot for the textarea element

CSS Properties

Name	Description
`--sl-text-area-rows`	The number of rows initially visible in the textarea

Keyboard interactions

Here's an overview of the common keyboard interactions associated with a text area:

Command	Description
Tab	When focus is outside the text area, moves focus to the input container. If focus is on the input container, moves focus to the end enhancer (if provided, and interactive).

WAI-ARIA

WAI-ARIA Roles, States, and Properties for a text area provide essential information to assistive technologies and screen readers. They convey the text area's role, state, and additional properties to ensure accessibility and a better user experience for individuals using assistive technology.Specifies whether the attribute is always set in the component (no) or it can be provided by the developer (yes)

Attribute	Value	Description	User supplied
`role`	`'textbox'`	Identifies as an element that allows the input of text.	no
`aria-label`	string	It is used to define a string that labels the action that will be performed when the user interacts with the text area. Needs to be added when the text area is not wrapped with `sl-form-field` and there is no `sl-label`.	yes
`aria-labelledby`	string	Used to connect with single header/element that describes the text area, when there is no label component connected to.	yes
`aria-required`	boolean	Informs the user that an element is required. When set to ‘true’, screen readers notify users that the element is required.	yes
`aria-disabled`	boolean	Announces the text area component as disabled with a screen reader. See [Note 1] below.	yes

Notes:

The aria-disabled should not be used as a one-for-one replacement for the disabled attribute because they have different functionalities:

disabled dims the text area visually, takes it out of the tab-focus sequence, prevents actions (click, enter) on it and announces it as 'dimmed' or 'disabled' in a screen reader.
aria-disabled only does the latter. You will need to disable the functionality yourself. This might be useful for scenarios where you don't want to take the text area out of the navigation flow.

When disabled is added to a text area there is no need to also add aria-disabled. Everything aria-disabled does, disabled does as well. You can read more on the difference and in which scenarios which option might be preferable on the MDN page about aria-disabled.

Interactive example