@workday/canvas-kit-docs/dist/mdx/react/text-area/TextArea.mdx

Documentation components of Canvas Kit components

import {
  ExampleCodeBlock,
  Specifications,
  SymbolDoc,
} from '@workday/canvas-kit-docs';
import Basic from './examples/Basic';
import Disabled from './examples/Disabled';
import Grow from './examples/Grow';
import LabelPosition from './examples/LabelPosition';
import Placeholder from './examples/Placeholder';
import RefForwarding from './examples/RefForwarding';
import Required from './examples/Required';
import ResizeConstraints from './examples/ResizeConstraints';


# Canvas Kit Text Area

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

[> Workday Design Reference](https://design.workday.com/components/inputs/text-area)

## Installation

```sh
yarn add @workday/canvas-kit-react
```

## Usage

### Basic Example

Text Area should be used in tandem with [Form Field](/components/inputs/form-field/) to ensure
proper label association and screen reader support.

<ExampleCodeBlock code={Basic} />

### Disabled

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

<ExampleCodeBlock code={Disabled} />

### Placeholder

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

<ExampleCodeBlock code={Placeholder} />

> **Accessibility Note**: Always provide a persistent `FormField.Label` and never rely on
> placeholder text as the only label for a text area. Placeholders can disappear or lack sufficient
> contrast. Use placeholders only for short format examples, and place detailed instructions or
> guidance in `FormField.Hint` instead of the placeholder.

### Ref Forwarding

Text Area supports [ref forwarding](https://reactjs.org/docs/forwarding-refs.html). It will forward
`ref` to its underlying `<textarea>` element.

<ExampleCodeBlock code={RefForwarding} />

### 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`

<ExampleCodeBlock code={ResizeConstraints} />

> **Accessibility Note**: Allowing users to resize the text area (default `resize: both`) improves
> accessibility by letting them adjust it for comfort. Avoid disabling resizing (`resize: none`)
> unless necessary, and always ensure the initial size meets the needs of your content.

### Grow

Set the `grow` prop of the Text Area to `true` to configure the Text Area to expand to the width of
its container.

<ExampleCodeBlock code={Grow} />

### Label Position Horizontal

Set the `orientation` prop of the Form Field to designate the position of the label relative to the
input component. By default, the orientation will be set to `vertical`.

<ExampleCodeBlock code={LabelPosition} />

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

<ExampleCodeBlock code={Required} />

### Error States

Form Field provides error and caution states for Text Area. Set the `error` prop on Form Field to
`"error"` or `"caution"` and use `FormField.Hint` to provide error messages. See
[Form Field's Error documentation](/components/inputs/form-field/#error-states) for
examples and accessibility guidance.

## Accessibility

`TextArea` should be used with [Form Field](/components/inputs/form-field/) to
ensure proper labeling, error handling, and help text association. See
[FormField's accessibility documentation](/components/inputs/form-field/#accessibility)
for comprehensive guidance on form accessibility best practices.

### Character Limits

When limiting text area length:

- Use the `maxLength` attribute to enforce the limit programmatically.
- For longer limits (100+ characters), consider adding character count information to
  `FormField.Hint`.
- Avoid announcing character counts after every keystroke, as this disrupts screen reader users.
  Check out
  [Debouncing an AriaLiveRegion: TextArea with character limit](https://workday.github.io/canvas-kit/?path=/docs/guides-accessibility-aria-live-regions--docs#debouncing-an-arialiveregion-textarea-with-character-limit)
  for an example of how to wait for users to stop typing before announcing the character count to
  screen readers.

### Screen Reader Experience

When properly implemented with `FormField`, screen readers will announce:

- The label text when the text area receives focus.
- Required, disabled, or read-only status.
- Help text and error messages (via `aria-describedby`).
- The current value or "blank" if empty.
- That it's a multi-line text input field.

## Component API

<SymbolDoc name="TextArea" fileName="/react/" />

## Specifications

<Specifications file="./cypress/component/TextArea.spec.tsx" name="Text Area" />