Components
Textarea
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.
Usage
pnpm dlx shadcn@latest add @opsinjs/textarea
The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.
import { Textarea } from "@/components/ui/textarea"<Textarea
aria-label="Anything you want to add?"
placeholder="A sentence or two is plenty."
rows={4}
/>Examples
textarea · base base · style base-lyraOpen under the product themeA notes field
Outside a Field, aria-label carries the prompt and the placeholder shows the kind of
answer wanted rather than repeating the question.
textarea-a-notes-field · base base · style base-lyraOpen under the product themeimport { Textarea } from "@/components/ui/textarea"
export default function TextareaANotesField() {
return (
<div className="w-full max-w-md">
<Textarea
aria-label="Anything you want to add?"
placeholder="A sentence or two is plenty."
rows={4}
/>
</div>
)
}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.
textarea-with-a-character-limit · base base · style base-lyraOpen under the product themeimport { Textarea } from "@/components/ui/textarea"
export default function TextareaWithACharacterLimit() {
return (
<div className="flex w-full max-w-md flex-col gap-opsin-2">
<label
htmlFor="textarea-limit"
className="text-opsin-headline [color:var(--foreground)]"
>
Add a short note
</label>
<Textarea
id="textarea-limit"
name="short-note"
maxLength={200}
rows={3}
placeholder="Keep it brief."
/>
<p className="m-0 text-opsin-footnote [color:var(--muted-foreground)]">
Up to 200 characters.
</p>
</div>
)
}When to use it
Use it when
- Collecting a free-text note the reader writes in their own words, such as how a day went.
- A question whose answer runs to a sentence or more, where a single-line box would hide the start.
- The control inside a Field for a long-answer question, where the field owns the label and the error.
Do not use it when
- The answer is a single short line, such as a name or a place.Use
fieldinstead. - The reader is entering a measurement with a unit, which needs the number formatted and the unit shown.Use
reading-inputinstead. - The reader is choosing from a fixed set of answers rather than writing one.Use
fieldinstead.
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-labelalone or anidwith a real<label htmlFor>gives it one, and with none ofaria-label,idornamea development warning names the gap. - A persistent visible label is recommended, not required, and the default export uses one.
invalidsetsaria-invalidand leaves the border neutral, because a form error is not a clinical status. Field places the message, so a standalone box cannot associate an external message id.maxLengthis 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: activeandprefers-contrast: more, including the browser's resize handle.
| Key | Action | Notes |
|---|---|---|
| Tab | Moves focus into the box | One tab stop. The box does not trap Tab, so a second Tab moves out. |
| Shift+Tab | Moves focus back out of the box | A single stop in reverse too, so focus leaves rather than stepping inside. |
| Enter | Inserts a line break | Native multi-line behaviour, so Enter adds a line rather than submitting. |
| Arrow keys, Home, End | Move the cursor through the text | The browser's own text editing bindings, not ones this component adds. |
Contrast: 36 measured token pairs, 15 below floor
| Pair | Theme | APCA Lc | WCAG 2.2 | Floor |
|---|---|---|---|---|
| body text on the page | light | 101.6 | 17.18:1 | Pass |
| body text on the page | dark | -100.5 | 18.00:1 | Pass |
| body text on a card | light | 104.7 | 17.96:1 | Pass |
| body text on a card | dark | -99.6 | 16.32:1 | Pass |
| body text on the muted ground | light | 98.1 | 16.32:1 | Pass |
| body text on the muted ground | dark | -97.5 | 13.77:1 | Pass |
| secondary text on the page | light | 83.9 | 7.42:1 | Pass |
| secondary text on the page | dark | -80.7 | 13.44:1 | Pass |
| secondary text on a card | light | 87.0 | 7.76:1 | Pass |
| secondary text on a card | dark | -79.8 | 12.19:1 | Pass |
| secondary text on the muted ground | light | 80.4 | 7.05:1 | Pass |
| secondary text on the muted ground | dark | -77.8 | 10.28:1 | Pass |
| a hairline boundary on the page | light | 19.3 | 1.41:1 | Below floor |
| a hairline boundary on the page | dark | -8.2 | 1.90:1 | Below floor |
| a hairline boundary on a card | light | 22.4 | 1.47:1 | Below floor |
| a hairline boundary on a card | dark | -7.3 | 1.72:1 | Below floor |
| a hairline boundary on the muted ground | light | 15.8 | 1.34:1 | Below floor |
| a hairline boundary on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on the page | light | 69.8 | 4.52:1 | Pass |
| a placeholder boundary on the page | dark | -51.0 | 7.62:1 | Pass |
| a placeholder boundary on a card | light | 72.8 | 4.72:1 | Pass |
| a placeholder boundary on a card | dark | -50.1 | 6.91:1 | Pass |
| a placeholder boundary on the muted ground | light | 66.2 | 4.29:1 | Pass |
| a placeholder boundary on the muted ground | dark | -48.1 | 5.83:1 | Pass |
| a placeholder fill on the page | light | 8.3 | 1.18:1 | Below floor |
| a placeholder fill on the page | dark | -8.2 | 1.90:1 | Below floor |
| a placeholder fill on a card | light | 11.4 | 1.23:1 | Below floor |
| a placeholder fill on a card | dark | -7.3 | 1.72:1 | Below floor |
| a placeholder fill on the muted ground | light | 0.0 | 1.12:1 | Below floor |
| a placeholder fill on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on its own fill | light | 58.9 | 3.84:1 | Pass |
| a placeholder boundary on its own fill | dark | -41.5 | 4.01:1 | Below floor |
| the card hairline on the page | light | 69.8 | 4.52:1 | Pass |
| the card hairline on the page | dark | -28.7 | 4.19:1 | Below floor |
| the card hairline on a card | light | 72.8 | 4.72:1 | Pass |
| the card hairline on a card | dark | -27.9 | 3.80:1 | Below floor |
These are the measured token pairs this component draws colour from, not a measurement of the component itself.
Props interface
Prop
Type
Generated from TextareaProps in registry/bases/base/textarea.tsx.
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.