Skip to content
flyingsalmon

Textarea

A multiline text field that owns its label, its error message, and its busyness, and grows with what the traveller types.

Installation

npx shadcn@latest add @flyingsalmon/textarea

Usage

import { useState } from 'react'

import { Textarea } from '@/components/ui/textarea'

export function TextareaUsage() {
  const [tripNotes, setTripNotes] = useState('')

  return (
    <Textarea
      label="Trip notes"
      value={tripNotes}
      onChange={(event) => setTripNotes(event.target.value)}
    />
  )
}

Examples

Autosize

The field grows to maxRows and then scrolls. Type past the fourth line to see the cap.

Description

Helper text sits under the field and joins its accessible description.

Everyone on the trip can read these

Error

The description stays where it is and the message grows in below it.

Everyone on the trip can read these

Write at least ten characters

Loading

Tab out to save. The spinner pins to the top-right corner while the save runs, the field stays editable, and a failed save becomes the field's own error.

Saves when you tab out. Add the word fail to see an error.

Disabled

The field and its label dim together and take no pointer events.

Read-only

The text stays readable and copyable on a muted background, and the field stays focusable.

Guidelines

When to use

  • For text that runs past one line: trip notes, a day-by-day itinerary, a message to the group.
  • When the length is up to the traveller and you want the field to grow instead of scrolling inside a fixed box.

When not to use

  • Use Input for one line of text such as a trip name or an email address.
  • Use Combobox when the traveller picks from options you control rather than writing freely.

Do and don’t

  • Do
    Make the empty field as tall as the answer you expect: two or three rows for a sentence, more for notes.The empty height tells the traveller how much to write. A one-row field invites a one-word answer.
  • Do
    Write the placeholder as a full example answer, such as "We land late, so keep the first evening free."A real sentence shows the kind and length of answer you want, and reads as an invitation rather than a blank to fill.
  • Do
    Word an error as what to write: "Tell us why you are leaving the plan, even in a few words."The traveller fixes a free-text field by writing, so the message hands them the start of the answer.
  • Don’t
    Offer a submit shortcut without naming it beside the submit button.Enter always makes a new line here, so a shortcut is invisible unless the screen names it. A hidden key only helps people who already guess it exists.
  • Don’t
    Lock the field while an autosave runs.A spinner in the corner shows the save and the traveller keeps typing; the next save picks up the new text.
  • Don’t
    Give the field a drag handle or a fixed height.The height follows the content up to a cap and then the field scrolls, so a manual size would fight it.

Accessibility

KeyDescription
TabMoves focus out of the field. It never inserts a tab character.
Shift+TabMoves focus to the previous control.
EnterInserts a newline. It does not submit the form.

Textarea generates the field id and wires the label to it, so clicking the label focuses the field. An error sets aria-invalid, and aria-describedby lists any ids you passed, then the error message, then the description. A loading field sets aria-busy and hides its spinner from screen readers, so the wait is announced once. required marks the label and reaches the <textarea>; the validation itself stays with your app. The field handles no submit shortcut: a key such as Cmd+Enter belongs to your form. The states every field shares are described on Fields.

API

Textarea

Also takes every <textarea> attribute except rows. className styles the wrapper.

PropTypeDefaultDescription
labelstring–The visible label. Renders above the field and is wired to it.
minRowsnumber3The height of the empty field, in rows. Set it to the length of answer you expect: a one-row field invites a one-word answer.
maxRowsnumber8The most rows the field grows to. Past it, the field scrolls.
descriptionstring–Helper text under the field.
errorstring–The failure message. Turns the border, the ring, and the label destructive.
loadingbooleanfalsePins a spinner to the top-right corner. The field stays editable. Set it, not disabled, while an autosave runs.
disabledbooleanfalseDims the field and its label and removes both from the tab order.
readOnlybooleanfalseKeeps the text readable on a muted background. The field stays focusable.
requiredbooleanfalseMarks the label and sets the native attribute.

  • Fields

    The label, description, error, loading, and disabled behaviour every field shares.
  • Input

    The single-line counterpart.
  • Form

    Lays fields out with an actions row and a result slot.