# Textarea

A form element that enables users to enter text on multiple lines.

Tabs: [Guidelines](/components/web/textarea/textarea.guidelines.md) · [Code](/components/web/textarea/textarea.code.md)

## Features

- Specify a max length for the text

- Set a max height to keep layout consistent

- Compatible with our [Form control](/components/web/form-control/form-control.guidelines) component

- Adheres to [our form accessibility guidelines](/patterns/forms/forms.accessibility).

## When to use

Use a text area to allow users to enter large amounts of text, such as descriptions, comments, or notes. For shorter text inputs, use the [Input](/components/web/input/input.guidelines) component.

## Examples

Information:

We promote usage of this component in combination with our [Form control](/components/web/form-control/form-control.guidelines) component to maintain layout consistency and ensure form accessibility. The Form control supports advanced use cases such as [hint text](/components/web/form-control/form-control.guidelines#hint-text), [help popovers](/components/web/form-control/form-control.guidelines#help-popover) and [error messages](/components/web/form-control/form-control.guidelines#error).

### Label

The label of a form element should be clear and concise, ideally under three words. It should describe the value of the element and not what the user needs to do in order to fill it out properly.

Information:

**Never omit a label**. Form labels are required for accessibility purposes. However, it may be acceptable to [hide the label visually](/patterns/forms/forms.accessibility#hiding-a-label-visually) in certain cases.

```tsx
<FormControl>
    <FormControl.Label>Expense description</FormControl.Label>
    <Textarea rows={3} name="description" />
</FormControl>
```

### Placeholder

In general, avoid using placeholder text. Putting instructions or important information in placeholder text isn't accessible. As soon as someone starts typing, that text vanishes, and people using auto-fill tools can't see it at all.

```tsx
<FormControl>
    <FormControl.Label>Feedback</FormControl.Label>
    <Textarea rows={3} name="description" placeholder={'Share your thoughts...'} />
</FormControl>
```

### Required or optional

Mark the minority of form elements in a form as required or optional. This helps users scan the form and understand what is required of them. Type out the word optional or required in the label. E.g. "Per purchase limit (optional)". Don't use asterisks or other symbols.

```tsx
<FormControl>
    <FormControl.Label>Expense description (required)</FormControl.Label>
    <Textarea rows={3} name="description" isRequired />
</FormControl>
```

### Hint text

Use hint text to give users clear guidance for data entry. Keep it brief and avoid repeating the label or other form details. If it feels redundant, try removing it. We keep help text above the input field to have the reading order match the visual order, which is needed for screen readers.

```tsx
<FormControl>
    <FormControl.Label>Expense description (required)</FormControl.Label>
    <FormControl.HintText>
        Provide a brief description of the cost, purpose, or any relevant context
    </FormControl.HintText>
    <Textarea rows={3} name="description" isRequired />
</FormControl>
```

### Help popover

Use help popovers to aid first-time users or to clarify complex concepts. The help popover can contain interactive content and may be used to provide links for further information.

```tsx
<FormControl>
    <FormControl.LabelWrapper>
        <FormControl.Label>Expense description</FormControl.Label>
        <FormControl.Help aria-label="Learn more about: Expense description">
            Expense descriptions help us accurately review your expense. By including a brief
            explanation of the cost, purpose, or any relevant context, you can speed up approval and
            ensure smooth reimbursement for out-of-pocket expenses.
        </FormControl.Help>
    </FormControl.LabelWrapper>
    <Textarea rows={3} name="card-limit" />
</FormControl>
```

### Error

Provide clear and helpful error messages that guide users toward a solution. Instead of merely stating the problem, ensure the message is specific and actionable. Avoid vague or shaming language.

```tsx
<FormControl>
    <FormControl.Label>Expense description (required)</FormControl.Label>
    <Textarea rows={3} name="description" isInvalid />
    <FormControl.Error>Enter an expense description</FormControl.Error>
</FormControl>
```

### Disabled

Disable a form element to indicate that it’s currently unavailable. This can be used to maintain layout consistency and communicate that the element may become available later. If the form element will never be available in a given context, leave it out.

```tsx
<FormControl>
    <FormControl.Label>Expense description</FormControl.Label>
    <Textarea rows={3} name="description" disabled />
</FormControl>
```

### Character count

Use a character counter to show the number of characters entered. This feature is particularly helpful when the text input must remain within a specific character limit.

```tsx
<FormControl>
    <FormControl.Label>Expense description</FormControl.Label>
    <Textarea rows={3} name="description" showCounter maxLength={200} />
</FormControl>
```

### Height

Set an initial height of the text area to guide the user towards the expected answer length. For instance, if the user is expected to enter an expense description with a maximum of 200 characters, an initial height of 3 rows might be appropriate.

```tsx
<FormControl>
    <FormControl.Label>Expense description</FormControl.Label>
    <Textarea rows={3} name="description" showCounter maxLength={200} />
</FormControl>
```

#### Fixed height

By default, the height of a text area is dynamic and grows with the input text. If you have a good reason to maintain a more consistent looking user interface, a fixed height can be defined.

> When a fixed height is defined, a scrollbar will appear if the text exceeds the height.

```tsx
<FormControl>
    <FormControl.Label>Expense description</FormControl.Label>
    <Textarea name="description" fixedHeight="50px" />
</FormControl>
```

## Accessibility

The implementation of this component has been informed by [our form accessibility guidelines](/patterns/forms/forms.accessibility).

## Best practices

Refer to our [Forms guidelines](/patterns/forms/forms.about) for general advice on forms structure, validation, and more.

## Related components

- [Form control](/components/web/form-control/form-control.guidelines): Form control displays a labelled input and, optionally, associated validation text, help popover, and/or hint text.
- [Input](/components/web/input/input.guidelines): A form element that enables users to enter a single line of text.