Textarea

Purpose

Use Textarea for longer free-form input such as notes, comments and multi-line descriptions.

Multi-line input

Release notes

Auto-grows as the copy becomes longer.

import { Textarea } from "@/components/ui/textarea";

export function Example() {
  return <Textarea aria-label="Notes" placeholder="Add notes" />;
}

Installation

With the Siteplane registry alias configured, add the component and import the installed source from your app.

CLI

pnpm dlx shadcn@4.16.1 add @siteplane/textarea

Import

import { Textarea } from "@/components/ui/textarea";
import { Button } from "@/components/ui/button";
import { Form } from "@/components/ui/form";
import { Label } from "@/components/ui/label";
import { InputGroup, InputGroupAddon, InputGroupText, InputGroupTextarea } from "@/components/ui/input-group";
import { Field, FieldDescription, FieldError, FieldLabel } from "@/components/ui/field";

Need the machine-readable source metadata? View registry JSON.

Usage

Use Textarea for multi-line input. Keep descriptions close through Field and avoid using it as a fixed-height display box.

import { Textarea } from "@/components/ui/textarea";

export function Example() {
  return <Textarea aria-label="Notes" placeholder="Add notes" />;
}

Examples

States, sizes, auto grow, field and input group compositions and form integration are props and compositions of the same primitive.

States

{/* Default */}
<Textarea aria-label="Team note" placeholder="Write a team note" />

{/* Disabled */}
<Textarea
  aria-label="Locked note"
  defaultValue="This note is locked for archived records."
  disabled
/>

{/* Invalid */}
<Textarea aria-invalid aria-label="Rejected note" defaultValue="Too short." />

Sizes

<Textarea aria-label="Small textarea" size="sm" />
<Textarea aria-label="Default textarea" />
<Textarea aria-label="Large textarea" size="lg" />
<Textarea aria-label="Extra large textarea" size="xl" />

Auto grow

{/* Grows with its content; no fixed rows needed. */}
<Textarea
  aria-label="Auto grow note"
  defaultValue="The textarea grows with content while keeping the control chrome clean."
/>

Field integration

Project summary

Shown in internal reviews and handoffs.

Escalation reason

<Field>
  <FieldLabel>
    <AlignLeftIcon className="size-4" />
    Project summary
  </FieldLabel>
  <Textarea placeholder="Summarize scope, risks, and next steps" />
  <FieldDescription>Shown in internal reviews and handoffs.</FieldDescription>
</Field>

<Field>
  <FieldLabel>
    <AlertCircleIcon className="size-4" />
    Escalation reason
  </FieldLabel>
  <Textarea aria-invalid defaultValue="Needs help" />
  <FieldError>Please describe the reason in at least one sentence.</FieldError>
</Field>

Input group compositions

Team note

Visible in the client workspace

{/* Leading icon */}
<InputGroup>
  <InputGroupAddon>
    <MessageSquareIcon />
  </InputGroupAddon>
  <InputGroupTextarea
    aria-label="Comment"
    placeholder="Add a customer-facing comment"
  />
</InputGroup>

{/* Block label */}
<InputGroup>
  <InputGroupAddon align="block-start">
    <InputGroupText>
      <FileTextIcon />
      Team note
    </InputGroupText>
  </InputGroupAddon>
  <InputGroupTextarea
    aria-label="Team note"
    defaultValue="Renewal risk should be reviewed before the next check-in."
  />
</InputGroup>

{/* Footer hint */}
<InputGroup>
  <InputGroupTextarea
    aria-label="Public summary"
    placeholder="Summarize the account status"
  />
  <InputGroupAddon align="block-end">
    <InputGroupText>Visible in the client workspace</InputGroupText>
  </InputGroupAddon>
</InputGroup>

Form integration

<Form onSubmit={onSubmit}>
  <Field name="message">
    <FieldLabel>Message</FieldLabel>
    <Textarea name="message" placeholder="Type your message here" required />
    <FieldError>This field is required.</FieldError>
  </Field>
  <Button loading={loading} type="submit">Submit</Button>
</Form>

Unstyled

unstyled drops the form control shell so a custom surface can provide its own; auto grow stays.

{/* Default keeps the form control shell. */}
<Textarea aria-label="Default note" placeholder="Default form control" />

{/* unstyled drops the shell so a custom surface provides its own. */}
<div className="rounded-lg border border-border border-dashed">
  <Textarea
    aria-label="Unstyled note"
    className="flex w-full"
    placeholder="Unstyled inside a custom shell"
    unstyled
  />
</div>

API Reference

The reference lists the source-owned exports and props that are easy to miss in visual examples. Inherited Base UI props remain available unless the wrapper narrows them.

Textarea accepts native textarea props plus size="sm" | "default" | "lg" | "xl".
size="xl" keeps the multiline minimum-height contract while adopting the customer-facing 16px field text. Use the surrounding provider's radius="sm" personality for the global 8px main corner.
The control supports native vertical resize and content-based auto sizing through the Siteplane styles.
Use InputGroupTextarea when leading, trailing or block add-ons belong directly to the same field.

Motion

Component motion uses the shared Siteplane motion contract. See the global motion guide for provider setup, tokens and reduced-motion behavior.

Textarea itself does not translate or scale. Focus, invalid and disabled states update without changing layout measurements.
Manual resize remains native browser behavior and requires no reduced-motion override.

Accessibility

Provide a visible label; placeholders are examples or hints, not accessible names.
Pair invalid state with FieldError and keep required, disabled and loading form state explicit.
Add-ons must not block focus or hide the native vertical resize affordance.

Implementation Guidance

Use Input for one-line values and Textarea for multi-line content.
Use InputGroupTextarea only for controls or hints directly coupled to the field.
Do not disable native resize or replace labels with placeholders without a product requirement.