UI Elements User Input Text Area

Updated: July 13, 2017
SAPUI5 Version 1.46

Text Area

sap.m.TextArea

Intro

The text area is an input control that allows the user to enter multiple lines of text.

Usage

Use the text area if you want to enter multiple lines of text. If you only want to enter a single line of text, use the text control instead.

Responsiveness

You can set the maximum number of lines to be shown. The amount of text depends on the size of the screen. On smaller screens, the user can scroll down the text area to see the entire text. To indicate that the text continues, the control shows only half of the last line. This also applies for mobile devices.

Components

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

Text area – Default
Text area – Default
Text area – Active state
Text area – Active state

You can also set a placeholder (input prompt), which is inherited from sap.m.InputBase; property: placeholder. The prompt text is displayed when the input field is empty.

Text area – With placeholder (input prompt)
Text area – With placeholder (input prompt)
Text area – Selected state
Text area – Selected state
Information
For information on how to manage leading and treading whitespace (blanks) when copying and pasting text into input controls, please see removing leading and trailing whitespace.

Behavior and Interaction

Entering and Removing Text

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

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

Text area – Limited
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
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 state
Text area – Disabled state

Growing behavior

With SAPUI5 version 1.38, the text area control acquired a growing property. It gives the control the ability to automatically grow and shrink with its content while the user is typing.

The maximum height of the text area is configurable but should be defined properly, that is, according to the space where the control will be located.

Growing text area: The text is aligned to the top of the text area; A new line is added to the bottom of the text area.
Growing text area: The text is aligned to the top of the text area; A new line is added to the bottom of the text area.

Styles

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

For more information, see form field validation.

Text area – Warning state
Text area – Warning state
Text area – Error state
Text area – Error state

Guidelines

  • As with other input fields in general, use a label. For exceptions regarding label usage, see the Exceptions 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 indicate the number of remaining characters and a countdown while the user is typing.
  • If you are applying the growing behavior of the text area, have in mind that its maximum height should not exceed the height of the screen.

Properties

  • You can provide a width by using the average character width (property: cols).
  • You can define the height of the text area via the lines of text (property: rows). You can also set the height of the text area (property: height), which would override the rows property.
  • Additionally, you can define the type of wrapping for the text area (property: wrapping) as Soft, Hard, or Off.
  • Since 1.38 the sap.m.TextArea has a growing property that enables text area’s height to change dynamically while the user is typing.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation