# Textarea

A multi-line text field with sm/default/lg sizes and an optional character counter.

- Category: Core Elements
- Page: https://wunderui.com/components/textarea
- Tier: Free

## Install

```bash
npx wunderui-cli add textarea
```

## Import

```tsx
import { Textarea, TextareaField, TextareaFieldProps, TextareaProps } from "@/components/ui/textarea"
```

## Minimal usage

Then use it:

```tsx
import { Textarea } from "@/components/ui/textarea"

export function Feedback() {
  return <Textarea id="feedback" label="Your feedback" placeholder="Tell us what happened" maxLength={200} showCount />
}
```

Expected result: The label Your feedback above a white box with a grey placeholder and the counter 0/200 in the corner. Clicking the label focuses the field.

## Usage

```tsx
import { Textarea } from "@/components/ui/textarea"

export function Example() {
  return (
    <Textarea
      id="message"
      label="Message"
      helper="Include steps to reproduce if you can."
      placeholder="Tell us what happened"
    />
  )
}
```

## When to use

### Use Textarea for

- Text over several lines, such as a message, a comment or feedback
- A description or a note that can be a paragraph or two
- A field with a limit that people should see while typing

### Use something else

- [Input](https://wunderui.com/components/input) for one line of text, such as a name or an email address
- [Prompt Input](https://wunderui.com/components/prompt-input) for a chat input that grows and has attach and send buttons

## Keyboard

A textarea is one tab stop and takes the keys of a native text field. Typing, selecting and system shortcuts are the browser's.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus into and out of the field. A disabled field is skipped; a read-only field keeps its place in the order. |
| `Enter` | Starts a new line. It does not send the form; give the form a button, or handle `Ctrl+Enter` yourself. |

## Behavior

What the textarea does itself, and what it leaves to the page.

- **A native element:** Textarea renders a native textarea inside a wrapper, so every attribute works: name, value, maxLength, required, readOnly, rows and the rest. The wrapper only holds the counter.
- **One component, two shapes:** With no field props it renders the bare field. With a label, helper, error or optional tag it adds label, control and message in one column, and an error appearing keeps the same textarea and focus.
- **Controlled or not:** Pass a value and change handler to own the text, or a default value to let the field keep it. The counter follows either way.
- **Size and density:** Size sets the minimum height: 72, 96 or 128 px by default, 80, 112 or 144 px at comfortable density. The field grows taller when the text does.
- **Counter:** Show count with a maximum length shows length and maximum in the bottom-right corner and adds room below the text. Without a maximum there is nothing to count, so no counter appears.
- **Resize:** By default people can drag the field taller. You can fix the height instead, or let the field grow with its text and add a maximum height so it scrolls at some point.
- **Invalid:** An error marks the field invalid, turns the border and focus ring red and replaces the helper with a red message, while the fill stays white. Without field props, it only reddens the border.
- **Disabled and read-only:** Disabled dims the field to 40 % with its label and helper, skips it in the tab order and leaves it out of the form data. Read-only stays readable, focusable, copyable and submitted, on a subtle fill.
- **Motion:** The border colour fades when the pointer enters or the field takes focus. Nothing moves or scales.
- **Reduced motion:** With reduced motion the same colour change stays, since it is a short fade and not movement.

## Anatomy

- `Label`: The visible name of the field. Clicking it focuses the textarea, and a field without a visible label needs an aria-label.
- `Textarea`: The multi-line field: a native textarea with a 1 px border and an 8 px corner. Its minimum height follows size and density (72, 96 or 128 px), and longer text scrolls inside.
- `Character counter`: Shows length and maximum in the bottom-right corner when both show count and a maximum are set. The field reserves room below the text, so the counter never covers a line.
- `Resize handle`: The browser's handle in the bottom-right corner that drags the field taller. It is on by default and can be removed.
- `Helper and error text`: A 12 px line under the field: a helper with the rule, or an error with what to do. The error replaces the helper, both are linked to the textarea, and an error also marks the field invalid.
- `TextareaField`
- `Textarea`

## Best practices

### When to use

- Use it for free text over several lines: a message, a description, feedback. One line goes in an Input, formatted text in a Rich Text Editor.

### Do

- Give it a visible label. A placeholder disappears with the first keystroke and isn't a name.
- Set a maximum length together with show count when there is a limit. The counter needs both, and the field stops accepting text at the limit.
- Say what to do in the error, such as Enter at least 20 characters, and keep what the person typed. Show it after they leave the field or send the form.
- Pick the size for the text you expect: small for a note, default for a message, large for a description. People can still drag the field taller.
- Mark the exception, not the rule. When most fields are needed, flag the few optional ones instead of putting a star on every other label.

### Don't

- Don't import TextareaField in new code. It is a deprecated alias, so use Textarea with the same props.
- Don't size it with rows or height classes. Pick a size instead, because the heights follow density and stay right in compact and comfortable.
- Don't hide the counter and cut the text off silently. A limit people can't see feels like a bug.
- Don't put a chat composer's buttons next to the field by hand. Put the field and its buttons in one box that owns the border and focus ring.

## API reference

### Textarea

| Prop | Type | Default | Description |
|---|---|---|---|
| error | React.ReactNode |  | The message under the field in the error colour. Sets `aria-invalid`, turns the border and the ring red and replaces `helper`. |
| helper | React.ReactNode |  | A hint under the field in 12 px tertiary text, linked with `aria-describedby`. Replaced by `error` while there is one. |
| label | React.ReactNode |  | The visible name of the field. Joined to the textarea with `htmlFor`. Any field prop makes Textarea render the label, the field and the message line instead of the bare field. |
| optional | boolean |  | Adds the tag `(optional)` after the label. It is part of the accessible name. |
| showCount | boolean |  | Shows a `length/maxLength` counter in the bottom-right corner and adds room below the text for it. It needs `maxLength`; without it nothing is drawn. |
| size | "default" \| "lg" \| "sm" |  | The minimum height of the field. `sm` is 72 px, `default` 96 px and `lg` 128 px at the default density, and 80, 112 and 144 px in `data-density="comfortable"`. People can still drag the field taller. |
| wrapperClassName | string |  | Class names for the column around label, field and message. `className` still goes to the `<textarea>`. |

Also accepts React.TextareaHTMLAttributes attributes.

### TextareaField

| Prop | Type | Default | Description |
|---|---|---|---|
| error | React.ReactNode |  | Error message below the field. Sets `aria-invalid` and `aria-describedby`. |
| helper | React.ReactNode |  | Hint below the field. Replaced by `error` while there is one. |
| label | React.ReactNode |  | Visible label. Joined to the control with `htmlFor`. |
| optional | boolean |  | Adds the "(optional)" tag to the label. |
| showCount | boolean |  | Show a "n/maxLength" character counter in the bottom-right corner. Requires maxLength. |
| size | "default" \| "lg" \| "sm" |  |  |
| wrapperClassName | string |  | Class names for the wrapper around label, field and message. |

Also accepts React.TextareaHTMLAttributes attributes.

## Examples

### Sizes: 72, 96 and 128 px

```tsx
import { Textarea } from "@/components/ui/textarea"

export function Example() {
  return (
    <Textarea placeholder="Enter text" aria-label="Enter text" />
  )
}
```

### Label, helper, error and counter: text, hint, requirement, message and limit

```tsx
import { Textarea } from "@/components/ui/textarea"

export function Example() {
  return (
    <Textarea
      id="feedback"
      label="Your feedback"
      placeholder="Tell us what happened"
    />
  )
}
```

### Resize: vertical, fixed and growing

```tsx
import { Textarea } from "@/components/ui/textarea"

export function Example() {
  // The default: the handle in the corner drags the field taller.
  return (
    <Textarea
      id="notes"
      label="Notes"
      placeholder="Write a note"
    />
  )
}
```

### States: default, hover, focus, filled, disabled, read-only and invalid

```tsx
import { Textarea } from "@/components/ui/textarea"

export function Example() {
  return (
    <Textarea
      id="message"
      label="Message"
      helper="Include steps to reproduce if you can."
      placeholder="Tell us what happened"
    />
  )
}
```

## In context

### Feedback: an optional field with a limit

The counter lives inside the field and shows only because there is a limit. Send stays off until there is text, and the message shows what happened.

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { Textarea } from "@/components/ui/textarea"

export function Example() {
  const [text, setText] = useState("")
  const [sent, setSent] = useState(false)

  return (
    <form
      className="flex flex-col gap-4"
      onSubmit={(event) => {
        event.preventDefault()
        setSent(true)
        setText("")
      }}
    >
      <Textarea
        id="feedback"
        label="Your feedback"
        optional
        helper="Include steps to reproduce if you can."
        placeholder="The export dialog forgets my last format…"
        value={text}
        maxLength={200}
        showCount
        onChange={(event) => {
          setText(event.target.value)
          setSent(false)
        }}
      />
      <div className="flex items-center justify-end gap-2">
        <p aria-live="polite" className="mr-auto text-sm text-text-secondary">
          {sent ? "Thank you, we read every message." : ""}
        </p>
        <Button type="button" variant="plain" onClick={() => setText("")}>
          Cancel
        </Button>
        <Button type="submit" variant="gradient" disabled={text.trim() === ""}>
          Send feedback
        </Button>
      </div>
    </form>
  )
}
```

### Composer: the field, the counter and Send in one box

The box owns the border and the focus ring; the field inside has none. The buttons have an 8 px corner with 8 px of air inside a 16 px box, so the corners are concentric.

```tsx
import { useState } from "react"
import { Paperclip, SendHorizontal } from "lucide-react"
import { Button } from "@/components/ui/button"
import { IconButton } from "@/components/ui/icon-button"
import { Textarea } from "@/components/ui/textarea"

const LIMIT = 2000

export function Example() {
  const [text, setText] = useState("")
  const [sent, setSent] = useState(false)

  return (
    <div className="flex flex-col gap-2">
      {/* A 16 px box with 8 px of air: the 8 px buttons inside it are concentric. */}
      <div className="rounded-xl border border-input bg-card p-2 transition-colors duration-fast ease-entrance hover:border-text-muted focus-ring-within">
        <Textarea
          aria-label="Message to Daniel Okafor"
          placeholder="Write a message"
          value={text}
          maxLength={LIMIT}
          onChange={(event) => {
            setText(event.target.value)
            setSent(false)
          }}
          className="min-h-16 resize-none border-transparent bg-transparent px-2 pt-2 pb-1 hover:border-transparent focus-visible:border-transparent! focus-visible:outline-none!"
        />
        <div className="flex items-center gap-2">
          <IconButton variant="ghost" size="sm" aria-label="Attach a file">
            <Paperclip />
          </IconButton>
          <span className="ml-auto text-xs text-text-tertiary tabular-nums">
            {text.length.toLocaleString("en-US")}/{LIMIT.toLocaleString("en-US")}
          </span>
          <Button
            size="sm"
            variant="gradient"
            disabled={text.trim() === ""}
            onClick={() => {
              setSent(true)
              setText("")
            }}
          >
            <SendHorizontal data-icon="inline-start" />
            Send
          </Button>
        </div>
      </div>
      <p aria-live="polite" className="min-h-5 text-sm text-text-secondary">
        {sent ? "Message sent to Daniel Okafor." : ""}
      </p>
    </div>
  )
}
```

### Feedback: a message that keeps what was typed

The error shows after the person leaves the field and replaces the helper line, saying how far the text is from the rule. Leave the field with a few words to see it; the text stays.

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { Textarea } from "@/components/ui/textarea"

const MIN = 20

export function Example() {
  const [text, setText] = useState("")
  const [touched, setTouched] = useState(false)
  const [sent, setSent] = useState(false)
  const short = text.trim().length < MIN
  const invalid = touched && short

  return (
    <form
      className="flex flex-col gap-4"
      noValidate
      onSubmit={(event) => {
        event.preventDefault()
        setTouched(true)
        setSent(!short)
      }}
    >
      <Textarea
        id="what-could-be-better"
        label="What could be better?"
        helper="At least 20 characters, so we can act on it."
        error={invalid ? `Write at least ${MIN} characters. You have ${text.trim().length}.` : undefined}
        placeholder="Describe the problem"
        maxLength={280}
        showCount
        value={text}
        onChange={(event) => {
          setText(event.target.value)
          setSent(false)
        }}
        onBlur={() => setTouched(true)}
      />
      <div className="flex items-center justify-end gap-2">
        <p aria-live="polite" className="mr-auto text-sm text-text-secondary">
          {sent ? "Feedback sent. Thank you." : ""}
        </p>
        <Button type="submit" variant="gradient">
          Send feedback
        </Button>
      </div>
    </form>
  )
}
```

### Support request: required and optional fields

A form where most fields are needed marks the exception: the steps are optional, the others carry no mark. Each field keeps its own helper line.

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { Input } from "@/components/ui/input"
import { Textarea } from "@/components/ui/textarea"

export function Example() {
  const [sent, setSent] = useState(false)

  return (
    <form
      className="flex flex-col gap-4"
      onSubmit={(event) => {
        event.preventDefault()
        setSent(true)
      }}
    >
      <Input id="subject" label="Subject" defaultValue="Export fails for a custom date range" required />
      <Textarea
        id="happened"
        label="What happened?"
        size="lg"
        helper="Say what you did and what you expected."
        defaultValue="I pick the last 90 days and press Export. The button stays disabled."
      />
      <Textarea
        id="steps"
        label="Steps to reproduce"
        optional
        helper="One step per line helps us find it faster."
        placeholder="1. Open Reports"
      />
      <Button type="submit" variant="gradient">
        Send request
      </Button>
      <p aria-live="polite" className="min-h-5 text-sm text-text-secondary">
        {sent ? "Request sent. We reply to info@wunderui.com within one business day." : ""}
      </p>
    </form>
  )
}
```

### Profile bio: a small field with a counter

The small size suits one or two sentences. The counter shows how much of the limit is used and the field stops at the limit; Save is a normal action, so it is a plain button.

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { Textarea } from "@/components/ui/textarea"

export function Example() {
  const [bio, setBio] = useState("Product lead at WunderUI. I write the release notes.")
  const [saved, setSaved] = useState(false)

  return (
    <div className="flex flex-col gap-4">
      <Textarea
        id="bio"
        label="Short bio"
        optional
        size="sm"
        helper="Shown on your profile next to your name."
        maxLength={160}
        showCount
        value={bio}
        onChange={(event) => {
          setBio(event.target.value)
          setSaved(false)
        }}
      />
      <div className="flex items-center justify-end gap-2">
        <p aria-live="polite" className="mr-auto text-sm text-text-secondary">
          {saved ? "Bio saved." : ""}
        </p>
        <Button variant="plain" onClick={() => setSaved(true)}>
          Save bio
        </Button>
      </div>
    </div>
  )
}
```

## For AI agents

`get_component("textarea")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
