Skip to content
opsinjs
Edit this page

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

Theme
Density
Text
Status
Accent theme
Accent
textarea · base base · style base-lyraOpen under the product theme

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.

Theme
Density
Text
Status
Accent theme
Accent
textarea-a-notes-field · base base · style base-lyraOpen under the product theme
textarea-a-notes-field.tsx
import { 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.

Theme
Density
Text
Status
Accent theme
Accent
textarea-with-a-character-limit · base base · style base-lyraOpen under the product theme
textarea-with-a-character-limit.tsx
import { 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 field instead.
  • The reader is entering a measurement with a unit, which needs the number formatted and the unit shown.Use reading-input instead.
  • The reader is choosing from a fixed set of answers rather than writing one.Use field instead.

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 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.
KeyActionNotes
TabMoves focus into the boxOne tab stop. The box does not trap Tab, so a second Tab moves out.
Shift+TabMoves focus back out of the boxA single stop in reverse too, so focus leaves rather than stepping inside.
EnterInserts a line breakNative multi-line behaviour, so Enter adds a line rather than submitting.
Arrow keys, Home, EndMove the cursor through the textThe browser's own text editing bindings, not ones this component adds.
Contrast: 36 measured token pairs, 15 below floor
PairThemeAPCA LcWCAG 2.2Floor
body text on the pagelight101.617.18:1Pass
body text on the pagedark-100.518.00:1Pass
body text on a cardlight104.717.96:1Pass
body text on a carddark-99.616.32:1Pass
body text on the muted groundlight98.116.32:1Pass
body text on the muted grounddark-97.513.77:1Pass
secondary text on the pagelight83.97.42:1Pass
secondary text on the pagedark-80.713.44:1Pass
secondary text on a cardlight87.07.76:1Pass
secondary text on a carddark-79.812.19:1Pass
secondary text on the muted groundlight80.47.05:1Pass
secondary text on the muted grounddark-77.810.28:1Pass
a hairline boundary on the pagelight19.31.41:1Below floor
a hairline boundary on the pagedark-8.21.90:1Below floor
a hairline boundary on a cardlight22.41.47:1Below floor
a hairline boundary on a carddark-7.31.72:1Below floor
a hairline boundary on the muted groundlight15.81.34:1Below floor
a hairline boundary on the muted grounddark0.01.45:1Below floor
a placeholder boundary on the pagelight69.84.52:1Pass
a placeholder boundary on the pagedark-51.07.62:1Pass
a placeholder boundary on a cardlight72.84.72:1Pass
a placeholder boundary on a carddark-50.16.91:1Pass
a placeholder boundary on the muted groundlight66.24.29:1Pass
a placeholder boundary on the muted grounddark-48.15.83:1Pass
a placeholder fill on the pagelight8.31.18:1Below floor
a placeholder fill on the pagedark-8.21.90:1Below floor
a placeholder fill on a cardlight11.41.23:1Below floor
a placeholder fill on a carddark-7.31.72:1Below floor
a placeholder fill on the muted groundlight0.01.12:1Below floor
a placeholder fill on the muted grounddark0.01.45:1Below floor
a placeholder boundary on its own filllight58.93.84:1Pass
a placeholder boundary on its own filldark-41.54.01:1Below floor
the card hairline on the pagelight69.84.52:1Pass
the card hairline on the pagedark-28.74.19:1Below floor
the card hairline on a cardlight72.84.72:1Pass
the card hairline on a carddark-27.93.80:1Below 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.