# Textarea

A multi-line text field.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Textarea.tsx)

## Overview

A textarea is a native `<textarea>` registered as the control of its enclosing field. Set `rows` to the expected length of the answer.

## Examples

### Basic

```tsx
import { Field, style, Textarea } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.grid()}>
      <Field.Root>
        <Field.Label>Notes</Field.Label>
        <Textarea placeholder="Add a note" />
      </Field.Root>
    </div>
  )
}

namespace styles {
  export const grid = style({
    alignItems: 'start',
    display: 'grid',
    gap: '24',
    gridTemplateColumns: 'repeat(auto-fill, minmax(min(280px, 100%), 1fr)) !custom',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Textarea/Basic.tsx)

### Variant

Set `variant` to `default` (default) or `outlined`, which draws a 1px line instead of the fill.

```tsx
import { Field, style, Textarea } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.grid()}>
      <Field.Root>
        <Field.Label>Notes</Field.Label>
        <Textarea defaultValue="Paid in full" />
      </Field.Root>
      <Field.Root>
        <Field.Label>Memo</Field.Label>
        <Textarea defaultValue="Rent for May" variant="outlined" />
      </Field.Root>
    </div>
  )
}

namespace styles {
  export const grid = style({
    alignItems: 'start',
    display: 'grid',
    gap: '24',
    gridTemplateColumns: 'repeat(auto-fill, minmax(min(280px, 100%), 1fr)) !custom',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Textarea/Variant.tsx)

### Resize

Set `resize` to `vertical` (default), `none`, or `auto`, which grows with the content.

```tsx
import { Field, style, Textarea } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.grid()}>
      <Field.Root>
        <Field.Label>Grows with content</Field.Label>
        <Textarea resize="auto" rows={1} />
      </Field.Root>
      <Field.Root>
        <Field.Label>Fixed height</Field.Label>
        <Textarea placeholder="Add a note" resize="none" />
      </Field.Root>
    </div>
  )
}

namespace styles {
  export const grid = style({
    alignItems: 'start',
    display: 'grid',
    gap: '24',
    gridTemplateColumns: 'repeat(auto-fill, minmax(min(280px, 100%), 1fr)) !custom',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Textarea/Resize.tsx)

### Invalid

Set `invalid` on `Field.Root` and add a `Field.Error` to show a validation message.

```tsx
import { Field, style, Textarea } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.grid()}>
      <Field.Root invalid>
        <Field.Label>Notes</Field.Label>
        <Textarea defaultValue="Too short" />
        <Field.Error match>Write at least 20 characters.</Field.Error>
      </Field.Root>
    </div>
  )
}

namespace styles {
  export const grid = style({
    alignItems: 'start',
    display: 'grid',
    gap: '24',
    gridTemplateColumns: 'repeat(auto-fill, minmax(min(280px, 100%), 1fr)) !custom',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Textarea/Invalid.tsx)

### Disabled

Set `disabled` on `Field.Root` to disable the textarea.

```tsx
import { Field, style, Textarea } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.grid()}>
      <Field.Root disabled>
        <Field.Label>Disabled</Field.Label>
        <Textarea defaultValue="Locked" />
      </Field.Root>
    </div>
  )
}

namespace styles {
  export const grid = style({
    alignItems: 'start',
    display: 'grid',
    gap: '24',
    gridTemplateColumns: 'repeat(auto-fill, minmax(min(280px, 100%), 1fr)) !custom',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Textarea/Disabled.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { Textarea } from '@tempoxyz/ds'

<Textarea />
```

## Guidelines

### When to Use

* Collect free text that may run over one line, such as a support message, a refund reason, or notes on a contact.
* Describe a new webhook, API key, or other object when a name alone isn't enough.

### When Not to Use

* Use [TextInput](/docs/components/text-input) for single-line values, even long ones such as a 0x address or a webhook URL.
* Use [Snippet](/docs/components/snippet) for a command or JSON payload to copy, not edit.
* Use [Select](/docs/components/select), [RadioGroup](/docs/components/radio-group), or [Checkbox](/docs/components/checkbox) when the answer fits a known set of options.

### Set Rows to the Expected Length

`rows` sets the starting height and defaults to 3. Size it to a typical answer.

**Do:** Give a long answer a few rows to start.

```tsx
/**
 * Do example for "Set Rows to the Expected Length" on the Textarea page.
 * Give a long answer a few rows to start.
 * @module
 */
import { Field, style, Textarea } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <Field.Label>Describe the issue</Field.Label>
      <Textarea rows={4} />
      <Field.Description>Include the transaction hash if you have one.</Field.Description>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })
}
```

**Don't:** Use a one-row textarea for a long answer. It reads as a single-line input.

```tsx
/**
 * Don't example for "Set Rows to the Expected Length" on the Textarea page.
 * Don't use a one-row textarea for a long answer. It reads as a single-line input.
 * @module
 */
import { Field, style, Textarea } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <Field.Label>Describe the issue</Field.Label>
      <Textarea resize="none" rows={1} />
      <Field.Description>Include the transaction hash if you have one.</Field.Description>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })
}
```

### Let the Box Grow

* **Drag to Resize (vertical):** The default. People drag the corner of the box down to make it taller.
* **Grow With Content (auto):** Grows through `field-sizing`. Other browsers keep the `rows` height.
* **Fixed Height (none):** Only when the layout can't absorb a taller box, such as a fixed-height card.

### Put Requirements in the Description

State what to include and any length limit in `Field.Description`, such as Up to 500 characters. There is no built-in character count.

Native `maxLength` cuts off pasted text without a warning. To keep pasted text, check the length in `validate` on `Field.Root` and explain the limit in `Field.Error`.

**Do:** State the limit before people start to write.

```tsx
/**
 * Do example for "Put Requirements in the Description" on the Textarea page.
 * State the limit before people start to write.
 * @module
 */
import { Field, style, Textarea } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <Field.Label>Reason for refund</Field.Label>
      <Textarea defaultValue="Sent 250.00 USDC to the wrong address." rows={3} />
      <Field.Description>Up to 500 characters.</Field.Description>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })
}
```

**Don't:** Reveal the limit only in an error.

```tsx
/**
 * Don't example for "Put Requirements in the Description" on the Textarea page.
 * Don't reveal the limit only in an error.
 * @module
 */
import { Field, style, Textarea } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root invalid {...styles.field()}>
      <Field.Label>Reason for refund</Field.Label>
      <Textarea defaultValue="Sent 250.00 USDC to the wrong address." rows={3} />
      <Field.Error match>Your message is too long.</Field.Error>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })
}
```

## Accessibility

`Textarea` renders a native `<textarea>` registered as the control of its `Field.Root`.

### Semantics

* **Textarea (textbox):** A native textarea, announced by screen readers as a multi-line text box.
* **Wiring (aria-describedby):** In a field, the label names it, and the field description and any shown error describe it.
* **Invalid State (aria-invalid):** Marks the control invalid and draws a red border. Explain the problem in `Field.Error`.
* **Disabled State (disabled):** Disables the native textarea, removes it from the tab order, and dims its label.

### Keyboard

* **Move Focus In and Out (Tab):** Moves focus to the textarea, and out of it again.
* **Insert a New Line (Enter):** Inserts a new line. It does not submit the form.

All other keys follow the native textarea.

### Your Responsibilities

* **Label the Textarea (Field.Label):** Give it a visible label in a field, or set `aria-label`. A placeholder isn't a label.
* **Keep Resizing (resize):** Keep resizing enabled where the layout allows, so readers who zoom can view their whole answer.

## Related

[TextInput](/docs/components/text-input)

Use for single-line text.

[Field](/docs/components/field)

Use for labels, descriptions, and errors.

[Snippet](/docs/components/snippet)

Use for read-only code and values.

[Forms](/docs/patterns/forms)

Covers laying out fields and actions.
