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

Documentation components of Canvas Kit components

import {ExampleCodeBlock, SymbolDoc, Specifications} from '@workday/canvas-kit-docs';

import Alert from './examples/Alert';
import Basic from './examples/Basic';
import Disabled from './examples/Disabled';
import Error from './examples/Error';
import Grow from './examples/Grow';
import LabelPositionVertical from './examples/LabelPositionVertical';
import LabelPositionHorizontal from './examples/LabelPositionHorizontal';
import HiddenLabel from './examples/HiddenLabel';
import Placeholder from './examples/Placeholder';
import RefForwarding from './examples/RefForwarding';
import Required from './examples/Required';
import ResizeConstraints from './examples/ResizeConstraints';


# Canvas Kit Text Area

<StatusIndicator variant="red">
  <StatusIndicator.Label>Deprecated</StatusIndicator.Label>
</StatusIndicator>

`TextArea` in Preview has been deprecated and will be removed in a future major version. Please use
[`FormField` in Preview](https://workday.github.io/canvas-kit/?path=/story/preview-inputs-form-field--basic)
instead.

TextArea's 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-preview-react
```

## Usage

### Basic Example

<ExampleCodeBlock code={Basic} />

### Disabled

Use `TextArea.Field`'s `disabled` prop to prevent users from interacting with the field.

<ExampleCodeBlock code={Disabled} />

### Placeholder

Use `TextArea.Field`'s `placeholder` prop to display a sample of its expected format or value before
a value has been provided.

<ExampleCodeBlock code={Placeholder} />

### Required

Use `TextArea.Field`'s `isRequired` prop (or use with the `useTextAreaModel` hook) to indicate that
the field is required. This will also add a red asterisk to `TextArea.Label`.

<ExampleCodeBlock code={Required} />

### Ref Forwarding

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

<ExampleCodeBlock code={RefForwarding} />

### Resize Constraints

Use the `resize` css attribute to restrict resizing of it to certain dimensions.

<ExampleCodeBlock code={ResizeConstraints} />

### Grow

There are lots of ways to accomplish this. The `TextArea.Field` extends from Box so it is easy to
extend full width, e.g. setting width prop to 100%, or you can set the `alignItems` prop to
`stretch` on `TextArea`, etc.

<ExampleCodeBlock code={Grow} />

### Label Position

Use the `orientation` property to set `TextArea.Label`'s position. You can override the default
spacing using the `gap` prop. Below are examples of both positions:

#### Horizontal

<ExampleCodeBlock code={LabelPositionHorizontal} />

#### Vertical

<ExampleCodeBlock code={LabelPositionVertical} />

### Visually Hiding The Label

If your label is just for screen reader users you can use the `accessibleHide` utility class from
`@workday/canvas-kit-react/common`. You will likely want to set the `gap` prop on `TextArea` to
`zero`.

<ExampleCodeBlock code={HiddenLabel} />

### Error States

Use the `hasError` property from `useTextAreaModel` to set the `TextArea` to the Error state. If you
have an accompanying hint you can use the `TextArea.Hint` subcomponent.

<ExampleCodeBlock code={Error} />

### Other Visual States

Use the `useThemedRing` hook to change the visual state of the `<textarea>` element.

#### Alert

<ExampleCodeBlock code={Alert} />

## Component API

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

## Specifications

<Specifications file="TextAreaPreview.spec.ts" name="Text Area" />