Skip to content
Browse documentation
whisk/ui

Textarea

Collect a longer text value.

Overview

Textarea is a native multiline control with Whisk/UI sizing, appearance, focus, and Field integration. Your application owns its value, validation timing, and submission.

Use when

The user enters or edits a longer text value.

Use instead

Use TextInput for a single line or Markdown to render formatted content.

Usage

import { Field, Textarea } from "@smoothie-framework/whisk-react";

<Field label="Release notes" required>
  <Textarea
    name="releaseNotes"
    rows={5}
    placeholder="Added audit-log filters."
  />
</Field>

Examples

Variants

Choose the frame treatment that fits the surrounding layout.

import { Field, FieldGroup, Textarea } from "@smoothie-framework/whisk-react";

<FieldGroup>
  <Field label="Filled">
    <Textarea variant="filled" rows={3} defaultValue="Atlas is ready for review." />
  </Field>
  <Field label="Outline">
    <Textarea variant="outline" rows={3} defaultValue="Atlas is ready for review." />
  </Field>
  <Field label="Flushed">
    <Textarea variant="flushed" rows={3} defaultValue="Atlas is ready for review." />
  </Field>
</FieldGroup>

Sizes

Choose the textarea size that matches the surrounding form density.

import { Field, FieldGroup, Textarea } from "@smoothie-framework/whisk-react";

<FieldGroup>
  <Field label="Small">
    <Textarea size="sm" rows={2} defaultValue="Atlas" />
  </Field>
  <Field label="Medium">
    <Textarea size="md" rows={3} defaultValue="Atlas" />
  </Field>
  <Field label="Large">
    <Textarea size="lg" rows={4} defaultValue="Atlas" />
  </Field>
</FieldGroup>

Helper text

Use Field description for concise guidance that helps someone complete the response.

Explain what changed for workspace members.
import { Field, Textarea } from "@smoothie-framework/whisk-react";

<Field
  label="Release notes"
  description="Explain what changed for workspace members."
  required
>
  <Textarea rows={4} placeholder="New audit-log filters" />
</Field>

Error text

Pass a clear validation message to Field after application validation finds a problem.

Add at least one rollout step.
import { Field, Textarea } from "@smoothie-framework/whisk-react";

<Field label="Migration plan" error="Add at least one rollout step.">
  <Textarea rows={5} />
</Field>

Forms

Use react-hook-form for registration and validation. register works because Textarea forwards its ref and native textarea props.

import { useForm } from "react-hook-form";
import { Box, Button, Field, Stack, Textarea } from "@smoothie-framework/whisk-react";

type FeedbackValues = { feedback: string };

function onSubmit(values: FeedbackValues) {
  // Send values to your application.
}

export function FeedbackForm() {
  const { register, handleSubmit, formState: { errors } } = useForm<FeedbackValues>();

  return (
    <Box as="form" noValidate onSubmit={handleSubmit(onSubmit)}>
      <Stack gap={3}>
        <Field label="Feedback" required error={errors.feedback?.message}>
          <Textarea {...register("feedback", { required: "Share your feedback." })} rows={4} />
        </Field>
        <Button type="submit">Send feedback</Button>
      </Stack>
    </Box>
  );
}

Disabled

Use disabled when the value is unavailable. Use readOnly instead when people still need to focus or copy it.

import { Field, Textarea } from "@smoothie-framework/whisk-react";

<Field disabled label="Workspace notes">
  <Textarea rows={4} defaultValue="Workspace provisioning is in progress." />
</Field>

Read-only

Use readOnly when people need to focus or copy the text but cannot edit it.

import { Field, Textarea } from "@smoothie-framework/whisk-react";

<Field label="Audit record">
  <Textarea rows={4} readOnly defaultValue="Workspace role updated by Maya Chen." />
</Field>

Resize

Use vertical resizing when extra space is useful. Avoid both in a constrained layout because horizontal resizing can break the surrounding frame.

import { Field, Textarea } from "@smoothie-framework/whisk-react";

<Field label="Implementation notes">
  <Textarea rows={5} resize="vertical" defaultValue="Record decisions and follow-up work." />
</Field>

Autoresize

Use autoresize when the text should grow with its content. Cap it with native style or an application class; current Chrome, Edge, Firefox, and Safari support field-sizing, while older browser versions keep the normal resize affordance.

import { Field, Textarea } from "@smoothie-framework/whisk-react";

<Field label="Short update">
  <Textarea
    autoresize
    resize="vertical"
    style={{ maxHeight: "16rem" }}
    defaultValue="The deployment is ready for review."
  />
</Field>

Character counter

InputCharacterCount reads the Field-owned textarea and is visible below it. It is not announced while typing; pair it with maxLength when the limit is enforced.

0
Up to 280 characters.
import { Field, InputCharacterCount, Stack, Textarea } from "@smoothie-framework/whisk-react";

<Field label="Release summary" description="Up to 280 characters.">
  <Stack gap={1}>
    <Textarea maxLength={280} rows={4} defaultValue="Atlas is ready for review." />
    <InputCharacterCount aria-label="Release summary characters" />
  </Stack>
</Field>

Focus rings

Set the ring placement only when the default does not meet the surrounding visual boundary. focusVisibleRing overrides focusRing for keyboard-visible focus.

import { Field, FieldGroup, Textarea } from "@smoothie-framework/whisk-react";

<FieldGroup>
  <Field label="Inside">
    <Textarea focusRing="inside" rows={3} defaultValue="Search project notes" />
  </Field>
  <Field label="Outside">
    <Textarea focusRing="outside" rows={3} defaultValue="Workspace context" />
  </Field>
  <Field label="Keyboard only">
    <Textarea focusRing="inside" focusVisibleRing="outside" rows={3} defaultValue="Agent instructions" />
  </Field>
</FieldGroup>

Clearable

Keep the value in application state. onInput keeps it synchronized on every keystroke in both adapters. InputGroupClear defaults to the accessible name “Clear input”.

import { useRef, useState } from "react";
import { Field, InputGroupClear, Textarea, TextareaGroup } from "@smoothie-framework/whisk-react";

export function NotesInput() {
  const textareaRef = useRef<HTMLTextAreaElement | null>(null);
  const [notes, setNotes] = useState("Review the billing migration.");

  return (
    <Field label="Notes">
      <TextareaGroup
        clearAction={<InputGroupClear controlRef={textareaRef} onClear={() => setNotes("")} />}
      >
        <Textarea
          ref={textareaRef}
          rows={4}
          value={notes}
          onInput={(event) => setNotes(event.currentTarget.value)}
        />
      </TextareaGroup>
    </Field>
  );
}

Actions

Use TextareaGroup when a textarea needs a stable frame and an application-owned action.

import { Button, Field, Textarea, TextareaGroup } from "@smoothie-framework/whisk-react";

<Field label="Draft reply">
  <TextareaGroup actions={<Button type="button" variant="secondary">Preview</Button>}>
    <Textarea rows={5} placeholder="Thank you for the detailed report." />
  </TextareaGroup>
</Field>

Props

Component props

PropTypeDefaultDescription
value | defaultValuestringnoneControl the current native value or seed an uncontrolled editing session. Neither submits or persists the text on its own.
placeholderstringnoneShow an example when empty.
rows | colsnumberbrowser defaultSet the initial visible editing area. Rows does not limit the text or replace a maximum height.
resizenone | vertical | horizontal | bothverticalControl how the user can resize the field.
autoresizebooleanfalseRequest native CSS content sizing. Browsers without field-sizing retain ordinary resize behavior; no resize observer is added.
scrollbarWidthauto | thinautoChoose the browser scrollbar width when content overflows.
sizesm | md | lgmdChoose the editing density.
variantfilled | outline | flushedfilledChoose the visual frame treatment.
name | form | autoCompletenative textarea attributesnoneParticipate in forms and give the browser a useful autofill hint.
minLengthnumbernoneSet the native minimum character constraint. Application validation still decides when feedback appears and whether submission succeeds.
maxLengthnumbernoneSet the native maximum character constraint and pair it with visible limit guidance when it matters.
requiredbooleanfalseSet the native required constraint. Field shares it with its one nested control.
disabled | readOnly | invalidbooleanfalseSet availability or invalid state. Pair invalid with visible error feedback from Field.
focusRing | focusVisibleRinginside | outside | mixed | nonetheme defaultConfigure focus-ring placement, with focusVisibleRing taking precedence for keyboard-visible focus.
TextareaGroup actions | clearActionReactNodenoneTextareaGroup wraps exactly one Textarea and can add application-owned bottom-row actions or a focus-revealed clear action.

Shared props

PropSupportedNotes
as / asChildNoTextarea always renders its native textarea host.
Style propsNoTextarea exposes semantic textarea props instead of the shared style-prop surface. See Style props.
className / styleYesApplied to the native textarea.
refYesForwards to the native textarea.
Native HTML attributesYesNative textarea attributes are forwarded.

Accessibility

Give every Textarea a visible Field label or an accessible name; a placeholder does not name the control. Explain a meaningful character limit in visible supporting text, and pair invalid state with a specific Field error. Keep the native resize affordance unless the surrounding interaction has a clear alternative, and use readOnly rather than disabled when people need to select or copy the text.

Content guidance

Name the content in its label and say what belongs in a description when the expected detail is not obvious. Keep placeholder examples short.