Intro

The text area is an input control that lets users enter multiple lines of text in a single field.

Text area default

When to Use

Use the text area:

Use the text area when users need to enter multiple lines of text.

Don't

Don’t use the text area:

If only a single line of input is required, use the input field instead.

Anatomy

Anatomy of text area

Input field: Container where users enter multi-line text.
Text: Placeholder or typed text. The placeholder is an optional prompt text that is displayed when the input field is empty.
Scrollbar (optional): Appears when the text exceeds the visible area, allowing users to scroll vertically.
Counter (optional): Displays how many characters remain or exceed the limit, if a character limit is set. The counter updates dynamically as the user types.

Behavior and Interaction

The text area allows the user to enter multiple lines of text.

Text area - default

Text area - while editing

You can also set a placeholder (input prompt), which is inherited from sap.m.InputBase (property: placeholder).

Text area - with placeholder (input prompt), active text area, edit in text area.

A: The placeholder appears when the field is empty.

B: As soon as the user starts typing, the placeholder disappears. It appears again when the user removes all the content from the text area.

C: The user can also select and edit the written text.

information

For information on how to manage leading and trailing white space (blanks) when copying and pasting text into input controls, see removing leading and trailing white space.

Entering and Removing Text

You can also limit the number of characters a user can enter. In this case, the text area prevents the user from adding more characters than the maximum value defined (property: maxLength). For more information, see Text Area Counter.

Text area – limited

Making Text Non-Editable

You can set the text area to non-editable (property: editable). This mode still allows the user to scroll to the text that is currently hidden.

Text area – read-only

Disabling Text

You can also set the text area to “disabled”. In this case, the user cannot edit or scroll (property: enabled).

Text area – disabled

Growing Behavior

The growing property lets the text area expand or shrink dynamically while the user types. You can define a maximum height to fit the layout space.

The text is aligned to the top of the text area.

As the user continues to type, a new line is added to the bottom of the text area.

Text Area Counter

If you have set a character limit for the text box (property: maxLength), you can use the text area counter to show a character count (remaining characters, characters over the limit).

To turn on the counter, set the property showExceededText to true. The user can then see all inserted characters, including those that are over the limit.

Text area counter – default state (counter is within the limit)

Text area counter – counter over the limit

The number of characters allowed is displayed below the text area, aligned to the right. A label below the field indicates how many characters are remain.

When the characters used are over the limit:

Тhe user can continue typing.
The counter updates as the user types.
We recommend changing the text area to a warning state.

When the user pastes copied text, characters that are over the limit are selected automatically. The user can delete any excess characters by pressing Delete or Back on the keyboard (or virtual keyboard for phones and tablets).

hint

If the text area already has a value state and the text length exceeds the limit, the value states are displayed in the following order (highest to lowest priority):

Additional error state available: This results in a higher priority (error + warning = error). If an error state is set, the text area is shown in an error state. When the error is fixed, the text area returns to the warning state until the character count is within the limit.
Additional warning state available: An additional warning state has the same priority as the counter warning state (warning + warning = warning). The text area stays in the warning state until all of the issues are fixed. The warning state set by the developer has the higher priority.
Additional success state available: In this case, the warning state has higher priority (success + warning = warning). Once the text count is within the limit, the text area shows the success state.

Styles

As with any other input control, you can validate the fields and show the result as a value state of the control (property: valueState). Possible value states are warning, error, success, information, or neutral (none).

For more information, see Semantic and Industry-Specific Colors and Form Field Validation.

Text area – warning state

Text area – error state

Text area - success state

Text area - information state

Guidelines

As with other input fields, use a label. For exceptions regarding label usage, see the Guidelines section of the Label article.
The placeholder does not substitute a label. It can be used to give an additional hint, but should not repeat the label in long format.
If you want to use the text area with a fixed text length (property: maxLength), for example, inside a form, use text beside the text area to count down the number of remaining characters while the user is typing.
If you are applying the growing behavior of the text area, bear in mind that its maximum height should not exceed the height of the screen.
As a display mode equivalent, consider using an expandable text.

Saving Forms with a Text Area Counter

If a text exceeds the limit for the text area, there are two options for saving the form:

The form can be saved, but only contains the text within the character limit. If you follow this approach, inform the user that only part of the text will be saved. In this case, we strongly recommend setting the text area state to “warning” to indicate that there is a problem with the text.
The form cannot be saved until the user edits the text and the character count is within the limit. In this case, we strongly recommend setting the text area state to “error”.

Properties

You can provide a width by specifying the average character width (property: cols).
You can define the height of the text area by specifying the number of lines of text (property: rows). You can also set the height of the text area (property: height), which overrides the rows property.
You can define the type of wrapping for the text area (property: wrapping) as soft, hard, or off.
sap.m.TextArea has a growing property that enables the height of the text area to change dynamically while the user is typing.
sap.m.TextArea can show a count for the number of permitted characters, and allow users to type/paste text over the limit (property: showExceededText). This property determines whether characters that exceed the character limit are visible.
- If this property is set to false, the user is not allowed to exceed the number of characters set in the maxLength property.
- If this property is set to true, characters exceeding the maxLength value are selected on paste, and the counter below the input field displays the number of characters that are over the limit.
To provide additional information for assistive technologies like screen readers, use ariaDescribedBy and ariaLabelledBy.

Localization

The text area supports both left-to-right (LTR) and right-to-left (RTL) reading directions. In LTR mode, the text is left-aligned while the character counter is right-aligned. In RTL mode, they are mirrored – the text is right-aligned, while the character counter is left-aligned.