Text Area

Anatomy

1. Label: Title of the Text Area.
2. Input Container: Rectangular container that houses the placeholder and body text.
3. Placeholder/Body Text: Placeholder text is optional and shows an example of how the text is used.

Usage Guidance

• Use the Text Area component when you need to let users enter an amount of text that’s longer than a single line.
• To ensure we don’t overwhelm users, there shouldn’t be more than two Wide Text Areas on a page.
• For all Text Areas on Web, a user clicking into a field or label that's not disabled will trigger the text cursor to appear, allowing users the ability to type. As the user types in the Text Area, the placeholder text is replaced with the user’s input.

When to Use

• Use the Text Area to fit longer text descriptions, usually around one paragraph.

When to Use Something Else

• Use a Rich Text Editor to give users the ability to format text.
• Use a Text Input for single line of text.

Examples

Basic Example

Text Area should be used in tandem with Form Field to meet accessibility standards.

Disabled

Set the disabled prop of the Text Area to prevent users from interacting with it.

Placeholder

Set the placeholder prop of the Text Input to display a sample of its expected format or value before a value has been provided.

Ref Forwarding

Text Area supports ref forwarding. It will forward ref to its underlying <textarea> element.

Resize Constraints

Set the resize prop of the Text Area to restrict resizing of it to certain dimensions. resize accepts the following values:

• TextArea.ResizeDirection.Both (Default)
• TextArea.ResizeDirection.Horizontal
• TextArea.ResizeDirection.None
• TextArea.ResizeDirection.Vertical

Grow

Set the grow prop of the wrapping Form Field to true to configure the Text Area to expand to the width of its container.

The grow prop may also be applied directly to the Text Area if Form Field is not being used.

Label Position

Set the labelPosition prop of the wrapping Form Field to designate the position of the label relative to the Text Area. labelPosition accepts the following values:

• FormField.LabelPosition.Top (Default)
• FormField.LabelPosition.Left

Required

Set the required prop of the wrapping Form Field to true to indicate that the field is required. Labels for required fields are suffixed by a red asterisk.

Error States

Set the error prop of the wrapping Form Field to FormField.ErrorType.Alert or FormField.ErrorType.Error to set the Text Area to the Alert or Error state, respectively. You will also need to set the hintId and hintText props on the Form Field to meet accessibility standards.

The error prop may be applied directly to the Text Area with a value of TextArea.ErrorType.Alert or TextArea.ErrorType.Error if Form Field is not being used.

Alert

Error

Component API

ErrorType

Specifications

Accessibility Guidelines

How Text Areas Impact the Accessible Experience

Programmatically associating labels and instructions to a form input is one of the most important foundational practices for building accessible forms.

For Text Area, placeholder values are best used for hints or examples of valid input. Designers should avoid relying on placeholder text for explaining the purpose of the input, as placeholders often don’t provide enough contrast against the text input background. In addition to lower contrast, placeholders disappear once users enter information, impacting users with memory loss, cognitive disabilities, or who are simply distracted.

Keyboard Interaction

Each Text Area must have a focus indicator that is highly visible against the background and against the non-focused state. Refer to Accessible Colors for more information.

Text Area must support the following keyboard interactions:

• Tab: focus into and out of each text area

Screen Reader Interaction

Text Area must communicate the following to users:

• This component is a multi-line text field
• The accessible name (label) describing the purpose of the field
• Text or placeholder values inside the field
• If applicable, whether the field is required, disabled, or invalid

Design Annotations Needed

• No design annotations needed

Implementation Markup Needed

• Text Area must have an aria-describedby attribute referencing the unique id value of the error text when an inline alert or error is shown.
• Text Area must have a required attribute when the field is required for form submission.
• [Included in component] A <label> element must be added with a for attribute referencing the unique id value of the associated text area.
• [Included in component] An aria-invalid=”true” attribute must be set on the Text Area when the field has an error condition.
• [Included in component] A disabled attribute must be set on the Text Area when the field is disabled.

Content Guidelines

• Refer to the guidelines on Placeholder Text in the Content Style Guide for more tips on how to write placeholder text.

Anatomy

1. Label: Title of the Text Area.
2. Input Container: Rectangular container that houses the placeholder and body text.
3. Placeholder/Body Text: Placeholder text is optional and shows an example text entry or instructional text.

Interaction States

Text Areas support inactive, active, and disabled interaction states.

Inactive states are the default state if the text area is not active, disabled, or displaying an alert.

Active states are displayed with a blue border, a cursor, and a keyboard.

Disabled states are grayed out to prevent users from interacting with the text area.

When pressing on the text area, the container fill changes to gray to provide touch feedback to the user.

Notification States

Notification states on mobile include additional visual affordances. They include an icon and a notification label.

Variations

Dynamic Height

This is the default behavior. Dynamic height text areas have a fixed base height that grows as the height of the content exceeds the initial height.

Fixed Height

Fixed height text areas should be used for data dense pages. Their fixed size helps reduce the overall density and visual load on the page.

If content exceeds the height of the Text Area, users can scroll within the input field to view the rest of the text. When inactive, content is shown to overflow at the bottom. When active, the content is scrollable, indicated by a scrollbar that appears within the text area. When typing, the content pushes up, leaving the cursor at the bottom of the input.

Usage Guidance

• To ensure we don’t overwhelm users, a max of two Text Areas per page is recommended.
• On iOS and Android devices, tapping into a field that is not disabled will cause a cursor to appear as well as a keyboard. As the user types within the Text Area, placeholder text is replaced with the user’s input. Tapping outside of the Text Area should trigger the inactive state.

When to Use

• Use when you need to enter an amount of text that’s longer than a single line.

When to Use Something Else

• Use a Text Input for a single line of text.
• Use a Time Picker if the user is inputting a time.
• Use a Date Picker if the user is inputting a date.
• Use a Rich Text Editor if input styling is needed.
• Use a Select dropdown, Radio Button, or Checkbox if inputted data is predetermined.

Mobile Guidance

Mobile Text Areas have larger typography for increased readability on smaller screens.

API Documentation

Component Definition

LabelledTextArea

public struct LabelledTextArea: View

CanvasKit design TextArea

Properties

body

public var body: some View

Methods

init(text:placeholderText:label:accessibilityLabel:helperText:context:isExpandable:)

public init(
    text: Binding<String>,
    placeholderText: String?,
    label: String,
    accessibilityLabel: String,
    helperText: String?,
    context: Binding<SemanticContext>,
    isExpandable: Bool = true
)

Create an instance of LabelledTextArea.

Parameters

init(text:placeholderText:label:helperText:context:isExpandable:localizer:)

public init(
    text: Binding<String>,
    placeholderText: String? = "",
    label: String,
    helperText: String?,
    context: Binding<SemanticContext>,
    isExpandable: Bool = true,
    localizer: LocalizationAdapting
)

Accessibility Guidelines

Refreshed mobile guidelines will be coming soon!

Content Guidelines

Refer to the guidelines on Placeholder Text in the Content Style Guide for more tips on how to write placeholder text.

Anatomy

1. Label: Title of the Text Area.
2. Input Container: Rectangular container that houses the placeholder and body text.
3. Placeholder/Body Text: Placeholder text is optional and shows an example text entry or instructional text.

Interaction States

Text Areas support inactive, active, and disabled interaction states.

Inactive states are the default state if the text area is not active, disabled, or displaying an alert.

Active states are displayed with a blue border, a cursor, and a keyboard.

Disabled states are grayed out to prevent users from interacting with the text area.

When pressing on the text area, the container fill changes to gray to provide touch feedback to the user.

Notification States

Notification states on mobile include additional visual affordances. They include an icon and a notification label.

Variations

Dynamic Height

This is the default behavior. Dynamic height text areas have a fixed base height that grows as the height of the content exceeds the initial height.

Fixed Height

Fixed height text areas should be used for data dense pages. Their fixed size helps reduce the density and visual load on the page.

If content exceeds the height of the text area, users can scroll within the input field to view the rest of the text. When inactive, content overflows at the bottom of the input. When active, the content is scrollable, indicated by a scrollbar that appears within the text area. When typing, content pushes up, leaving the cursor at the bottom of the input.

Usage Guidance

• To ensure we don’t overwhelm users, a max of two Text Areas per page is recommended.
• On iOS and Android devices, tapping into a field or label that is not disabled will cause a text cursor to appear as well as a corresponding keyboard. As the user types within the Text Area, any placeholder text is replaced with the user’s input. Tapping outside of the Text Area should trigger the inactive state.

When to Use

• Use when you need to enter an amount of text that’s longer than a single line.

When to Use Something Else

• Use a Text Input for a single line of text.
• Use a Time Picker if the user is inputting a time.
• Use a Date Picker if the user is inputting a date.
• Use a Rich Text Editor if input styling is needed.
• Use a Select dropdown, Radio, or Checkbox if inputted data is predetermined.

Mobile Guidance

Mobile Text Areas have larger typography for increased readability on smaller screens.

API Documentation

Component Definition

@Composable
fun NonInteractivePillUiComponent(
    modifier: Modifier = Modifier,
    label: String? = null,
    value: String,
    onValueChange: String -> Unit,
    readOnly: Boolean = false,
    textStyle: TextStyle = LocalTextStyle.current,
    placeholder: String? = null,
    placeholderTextStyle: TextStyle = WorkdayTheme.canvasTypography.bodyMedium,
    heightConfig: TextInputHeightConfig = TextInputHeightConfig.SingleLineConfig,
    interactionSource: MutableInteractionSource = remember { MutableInteractionSource() },
    leadingIcon: @Composable() -> Unit? = null,
    trailingIcon: @Composable() -> Unit? = null,
    visualTransformation: VisualTransformation = VisualTransformation.None,
    helperText: String? = null,
    onClickInputText: () -> Unit = {},
    onClickClearTextIcon: () -> Unit = {},
    keyboardOptions: KeyboardOptions = defaultKeyboardOptions(
        isSingleLine = heightConfig.isSingleLine
    ),
    keyboardActions: KeyboardActions = defaultKeyboardActions(),
    semanticState: SemanticState = SemanticState())
) {

Parameters

Accessibility Guidelines

Refreshed mobile guidelines will be coming soon!

Content Guidelines

Refer to the guidelines on Placeholder Text in the Content Style Guide for more tips on how to write placeholder text.