---
title: "Textarea"
description: "A multi-line box for a free-text note, a native textarea wearing the opsinjs tokens rather than a Base UI primitive, that takes neither colour axis."
url: "https://opsinjs.pensievelabs.org/docs/components/textarea"
source: "https://opsinjs.pensievelabs.org/docs/components/textarea.md"
section: "Components"
status: "shipped"
kind: "component"
category: "actions-and-forms"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["long text", "notes input"]
implemented: true
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> `<StubNotice>` IS THE EXCEPTION, AND IT IS THE ONE TO READ. It is a
> paired element rather than a self-closing one, and the text between
> its opening and closing tags is prose an author wrote, reproduced
> below word for word. That prose is where this page says whether the
> component has been reviewed. Read the children, not only the
> attributes.

<StubNotice
  name="textarea"
  status="shipped"
  questions="[
  &#x22;Whether the body ink, the muted placeholder and the neutral border clear the text and non-text contrast floors is argued from the roles, not measured.&#x22;,
  &#x22;Nobody has heard the box in a screen reader, so whether an unnamed box is caught rests on a development warning that only fires in development.&#x22;,
  &#x22;Whether a standalone invalid box is noticeable with only aria-invalid and the neutral border, before Field places a visible message, has not been tested with a reader.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="textarea" unbuilt="false" importPath="@/components/ui/textarea" />

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

```tsx
<Textarea
  aria-label="Anything you want to add?"
  placeholder="A sentence or two is plenty."
  rows={4}
/>
```

## Examples [#examples]

<ComponentPreview name="textarea" />

### A notes field [#a-notes-field]

Outside a Field, `aria-label` carries the prompt and the placeholder shows the kind of
answer wanted rather than repeating the question.

<ComponentPreview name="textarea-a-notes-field" kind="example" align="start" />

### With a character limit [#with-a-character-limit]

`maxLength` caps the text, and the footnote states the limit in words, because the
native attribute refuses the next keystroke in silence. A real `<label htmlFor>` pointed
at its `id` names this box.

<ComponentPreview name="textarea-with-a-character-limit" kind="example" align="start" />

## When to use it [#when-to-use-it]

<WhenToUse
  use="[
  &#x22;Collecting a free-text note the reader writes in their own words, such as how a day went.&#x22;,
  &#x22;A question whose answer runs to a sentence or more, where a single-line box would hide the start.&#x22;,
  &#x22;The control inside a Field for a long-answer question, where the field owns the label and the error.&#x22;,
]"
  avoid="[
  { case: &#x22;The answer is a single short line, such as a name or a place.&#x22;, instead: &#x22;field&#x22; },
  { case: &#x22;The reader is entering a measurement with a unit, which needs the number formatted and the unit shown.&#x22;, instead: &#x22;reading-input&#x22; },
  { case: &#x22;The reader is choosing from a fixed set of answers rather than writing one.&#x22;, instead: &#x22;field&#x22; },
]"
/>

## Accessibility [#accessibility]

Only neutral chrome roles reach the box, never a status colour, literal or ramp step,
and its type is the `body` step, not a pixel size. The focus ring rides in the box's own
classes, so it survives without the product stylesheet, and the height floors at the
house target. There is no axe, target-size, focus-visible or 320px reflow failure.

**Residual items.**

* The box needs an accessible name and invents none. A Field label, an `aria-label` alone
  or an `id` with a real `<label htmlFor>` gives it one, and with none of `aria-label`,
  `id` or `name` a development warning names the gap.
* A persistent visible label is recommended, not required, and the default export uses
  one.
* `invalid` sets `aria-invalid` and leaves the border neutral, because a form error is
  not a clinical status. [Field](./field.mdx) places the message, so a standalone box
  cannot associate an external message id.
* `maxLength` is forwarded with no visible counter or live remaining-count region, so
  pair the limit with a visible count near the box, as the Content guidelines say.
* Disabled state is a muted fill, not an opacity wash, so the text stays legible, and
  WCAG exempts disabled controls from the contrast floor.
* No gate checks contrast, or the box under `forced-colors: active` and
  `prefers-contrast: more`, including the browser's resize handle.

<KeyboardTable
  name="textarea"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Moves focus into the box&#x22;,
    notes: &#x22;One tab stop. The box does not trap Tab, so a second Tab moves out.&#x22;,
  },
  {
    keys: &#x22;Shift + Tab&#x22;,
    action: &#x22;Moves focus back out of the box&#x22;,
    notes: &#x22;A single stop in reverse too, so focus leaves rather than stepping inside.&#x22;,
  },
  {
    keys: &#x22;Enter&#x22;,
    action: &#x22;Inserts a line break&#x22;,
    notes: &#x22;Native multi-line behaviour, so Enter adds a line rather than submitting.&#x22;,
  },
  {
    keys: &#x22;Arrow keys, Home, End&#x22;,
    action: &#x22;Move the cursor through the text&#x22;,
    notes: &#x22;The browser's own text editing bindings, not ones this component adds.&#x22;,
  },
]"
/>

<ContrastReport component="textarea" />

## Props interface [#props-interface]

<PropsTable name="TextareaProps" />

`value` with `onChange` makes the box controlled, and `defaultValue` leaves it
uncontrolled. `rows` sets the resting height and defaults to three. `className` is
merged last and must resolve no `--opsin-status-*` or `--opsin-category-*` role.
