Text Area

Text Areas allow users to enter and edit multiple lines of text.

yarn add @workday/canvas-kit-react
Install
yarn add @workday/canvas-kit-react

Anatomy

Image of a Text Area in its default state with top label.

  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

Alert: Please enter your review.

Error

Error: Please enter your review.

Component API

TextArea

Props

Props extend from textarea. Changing the as prop will change the element interface.

NameTypeDescriptionDefault
disabledboolean

If true, set the TextArea to the disabled state.

false
error

The type of error associated with the TextArea (if applicable).

onChange(e: <>) => void

The function called when the TextArea state changes.

placeholderstring

The placeholder text of the TextArea.

readOnlyboolean

If true, set the TextArea to read-only. The user will be unable to interact with the TextArea.

false
resize

The resize constraints of the TextArea.

valueany

The value of the TextArea.

theme
growboolean

True if the component should grow to its container's width. False otherwise.

childrenReact.ReactNode
asReact.ElementType

Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using React.forwardRefand spread extra props to a root element.

Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.

textarea
refReact.Ref<R = textarea>

Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If as is set to an element, it will be that element. If as is a component, the reference will be to that component (or element if the component uses React.forwardRef).

TextArea.ErrorType

Basic type information:

ErrorType

TextArea.ResizeDirection

NameTypeDescriptionDefault
None'none'
Both'both'
Horizontal'horizontal'
Vertical'vertical'

Specifications

GivenWhenThen
given the 'Basic' story is rendered
    • it should not have any axe errors
    given the 'Basic' story is rendered
    • clicked
    • it should be focused
    given the 'Basic' story is rendered
    • text is entered
    • it should reflect the text typed
    given the 'Alert' story is rendered
      • it should not have any axe errors
      given the 'Alert' story is rendered
      • clicked
      • it should be focused
      given the 'Alert' story is rendered
      • text is entered
      • it should reflect the text typed
      given the 'Error' story is rendered
        • it should not have any axe errors
        given the 'Error' story is rendered
        • clicked
        • it should be focused
        given the 'Error' story is rendered
        • text is entered
        • it should reflect the text typed
        given the 'Disabled' story is rendered
          • it should not have any axe errors
          given the 'Disabled' story is rendered
            • it should be disabled
            given the 'Placeholder' story is rendered
              • it should not have any axe errors
              given the 'Placeholder' story is rendered
                • it should render a placeholder text
                given the 'Placeholder' story is rendered
                  • it should reflect the text typed
                  Source: TextArea.spec.ts

                  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.

                  Can't Find What You Need?

                  Check out our FAQ section which may help you find the information you're looking for.

                  FAQ Section