# Textarea

import { Callout } from "fumadocs-ui/components/callout";
import { Accordion, Accordions } from "fumadocs-ui/components/accordion";
import { Step, Steps } from "fumadocs-ui/components/steps";
import { Tabs, Tab } from "fumadocs-ui/components/tabs";
import {
  Badge,
  Button,
  Card,
  CardContent,
  CardHeader,
  CardTitle,
  Textarea,
} from "@pycolors/ui";
import {
  AlignLeft,
  ArrowRight,
  CheckCircle,
  ClipboardCheck,
  FileText,
  FormInput,
  MessageSquareText,
  MousePointerClick,
  PanelsTopLeft,
  PencilLine,
  Rows3,
  TextCursorInput,
  XCircle,
} from "lucide-react";
import { PreferAvoid } from "@/components/docs/prefer-avoid";
import { DocsLinks } from "@/components/docs/docs-links";
import { DocsFeatureGrid } from "@/components/docs/docs-feature-grid";

<div className="flex flex-wrap items-center gap-2">
  <Badge variant="outline">
    UI
  </Badge>

  <Badge>
    Textarea
  </Badge>
</div>

### Multi-line input for longer user intent

The **Textarea** component captures longer text than a standard Input.

Use it for:

* feedback messages
* support requests
* product descriptions
* notes
* prompts
* comments
* longer form fields

Textarea follows the same field model as `Input`: label, helper text, error state, generated id, and accessible descriptions.

<Callout title="Core idea">
  Use Textarea when the user needs space to express intent, context, or explanation.
</Callout>

### Import

```tsx title="textarea-import.tsx"
import { Textarea } from "@pycolors/ui";
```

### Basic usage

Use a label to make the field clear and accessible.

<Tabs items={["Preview", "Code"]}>
  <Tab value="Preview">
    <Preview>
      <div className="w-full max-w-xl">
        <Textarea label="Message" placeholder="Tell us what you are building..." />
      </div>
    </Preview>
  </Tab>

  <Tab value="Code">
    ```tsx title="basic-textarea.tsx"
    import { Textarea } from "@pycolors/ui";

    export function BasicTextarea() {
      return (
        <Textarea
          label="Message"
          placeholder="Tell us what you are building..."
        />
      );
    }
    ```
  </Tab>
</Tabs>

<Callout type="info" title="Label rule">
  Prefer a visible label. Use placeholder text for examples, not as the only field description.
</Callout>

## When to use Textarea

Use Textarea when one line is not enough for the task.

<DocsFeatureGrid
  columns={3}
  tone="platform"
  items={[
  {
    title: 'Feedback',
    description:
      'Capture user feedback, support details, and product requests.',
    icon: MessageSquareText,
  },
  {
    title: 'Descriptions',
    description:
      'Let users describe projects, products, workspaces, or templates.',
    icon: FileText,
  },
  {
    title: 'Notes',
    description:
      'Store internal notes, onboarding context, or review comments.',
    icon: PencilLine,
  },
]}
/>

### Helper text

Use helper text to explain what kind of answer is expected.

<Tabs items={["Preview", "Code"]}>
  <Tab value="Preview">
    <Preview>
      <div className="w-full max-w-xl">
        <Textarea label="Project description" helperText="Describe the product, target users, and current constraints." placeholder="A SaaS starter for founders who want to ship faster..." />
      </div>
    </Preview>
  </Tab>

  <Tab value="Code">
    ```tsx title="textarea-helper-text.tsx"
    import { Textarea } from "@pycolors/ui";

    export function TextareaHelperText() {
      return (
        <Textarea
          label="Project description"
          helperText="Describe the product, target users, and current constraints."
          placeholder="A SaaS starter for founders who want to ship faster..."
        />
      );
    }
    ```
  </Tab>
</Tabs>

<Callout title="Helper text rule">
  Helper text should reduce uncertainty. Keep it short, concrete, and connected to the task.
</Callout>

### Error state

Use the `error` prop for validation errors. It automatically sets `aria-invalid`, `aria-errormessage`, and error styling. The error text carries `role="alert"`, so it is announced immediately when it appears — including while the field is already focused. A consumer-supplied `aria-describedby` is composed with the field's own helper/error ids rather than replaced.

<Tabs items={["Preview", "Code"]}>
  <Tab value="Preview">
    <Preview>
      <div className="w-full max-w-xl">
        <Textarea label="Launch notes" placeholder="Summarize the release..." error="Launch notes must contain at least 20 characters." />
      </div>
    </Preview>
  </Tab>

  <Tab value="Code">
    ```tsx title="textarea-error.tsx"
    import { Textarea } from "@pycolors/ui";

    export function TextareaError() {
      return (
        <Textarea
          label="Launch notes"
          placeholder="Summarize the release..."
          error="Launch notes must contain at least 20 characters."
        />
      );
    }
    ```
  </Tab>
</Tabs>

<Callout type="info" title="Validation rule">
  Error text should explain what failed and how to fix it. Avoid vague messages like “Invalid value”.
</Callout>

### Required fields

Use `required` for mandatory fields. The label displays a destructive asterisk and the textarea receives `aria-required`.

<Tabs items={["Preview", "Code"]}>
  <Tab value="Preview">
    <Preview>
      <div className="w-full max-w-xl">
        <Textarea required label="Support request" helperText="Include the page, expected behavior, and what happened." placeholder="I expected..." />
      </div>
    </Preview>
  </Tab>

  <Tab value="Code">
    ```tsx title="textarea-required.tsx"
    import { Textarea } from "@pycolors/ui";

    export function TextareaRequired() {
      return (
        <Textarea
          required
          label="Support request"
          helperText="Include the page, expected behavior, and what happened."
          placeholder="I expected..."
        />
      );
    }
    ```
  </Tab>
</Tabs>

## Sizes

Textarea supports three design-system sizes: `sm`, `md`, and `lg`.

<Tabs items={["Preview", "Code"]}>
  <Tab value="Preview">
    <Preview>
      <div className="grid w-full max-w-xl gap-4">
        <Textarea size="sm" label="Small" placeholder="Compact notes..." />

        <Textarea size="md" label="Medium" placeholder="Default textarea..." />

        <Textarea size="lg" label="Large" placeholder="Longer product description..." />
      </div>
    </Preview>
  </Tab>

  <Tab value="Code">
    ```tsx title="textarea-sizes.tsx"
    import { Textarea } from "@pycolors/ui";

    export function TextareaSizes() {
      return (
        <div className="grid gap-4">
          <Textarea
            size="sm"
            label="Small"
            placeholder="Compact notes..."
          />

          <Textarea
            size="md"
            label="Medium"
            placeholder="Default textarea..."
          />

          <Textarea
            size="lg"
            label="Large"
            placeholder="Longer product description..."
          />
        </div>
      );
    }
    ```
  </Tab>
</Tabs>

### Size guidance

| Size | Best for                                     |
| ---- | -------------------------------------------- |
| `sm` | Compact notes, admin tables, dense forms     |
| `md` | Default forms and settings pages             |
| `lg` | Long descriptions, prompts, support messages |

### Resize behavior

The `resize` prop controls how users can resize the field.

<Tabs items={["Preview", "Code"]}>
  <Tab value="Preview">
    <Preview>
      <div className="grid w-full max-w-xl gap-4">
        <Textarea label="Vertical resize" resize="vertical" placeholder="Default behavior..." />

        <Textarea label="No resize" resize="none" placeholder="Fixed textarea..." />
      </div>
    </Preview>
  </Tab>

  <Tab value="Code">
    ```tsx title="textarea-resize.tsx"
    import { Textarea } from "@pycolors/ui";

    export function TextareaResize() {
      return (
        <div className="grid gap-4">
          <Textarea
            label="Vertical resize"
            resize="vertical"
            placeholder="Default behavior..."
          />

          <Textarea
            label="No resize"
            resize="none"
            placeholder="Fixed textarea..."
          />
        </div>
      );
    }
    ```
  </Tab>
</Tabs>

### Available resize options

| Resize       | Behavior                         |
| ------------ | -------------------------------- |
| `vertical`   | User can resize height           |
| `none`       | Fixed size                       |
| `horizontal` | User can resize width            |
| `both`       | User can resize width and height |

<Callout title="Resize rule">
  Prefer `vertical` for most product forms. Avoid horizontal resize in constrained layouts.
</Callout>

### Feedback form

<Tabs items={["Preview", "Code"]}>
  <Tab value="Preview">
    <Preview>
      <div className="w-full max-w-xl rounded-2xl border border-border/60 bg-card p-5">
        <div className="mb-4">
          <div className="text-sm font-medium text-foreground">
            Send feedback
          </div>

          <div className="mt-1 text-sm text-muted-foreground">
            Tell us what would make PyColors more useful.
          </div>
        </div>

        <Textarea label="Feedback" helperText="Share the problem, context, and expected improvement." placeholder="I would like..." />

        <div className="mt-4 flex justify-end">
          <Button>
            Send feedback
          </Button>
        </div>
      </div>
    </Preview>
  </Tab>

  <Tab value="Code">
    ```tsx title="feedback-form.tsx"
    import { Button, Textarea } from "@pycolors/ui";

    export function FeedbackForm() {
      return (
        <div className="rounded-2xl border border-border/60 bg-card p-5">
          <div className="mb-4">
            <div className="text-sm font-medium text-foreground">
              Send feedback
            </div>
            <div className="mt-1 text-sm text-muted-foreground">
              Tell us what would make PyColors more useful.
            </div>
          </div>

          <Textarea
            label="Feedback"
            helperText="Share the problem, context, and expected improvement."
            placeholder="I would like..."
          />

          <div className="mt-4 flex justify-end">
            <Button>Send feedback</Button>
          </div>
        </div>
      );
    }
    ```
  </Tab>
</Tabs>

### Prompt field

<Tabs items={["Preview", "Code"]}>
  <Tab value="Preview">
    <Preview>
      <div className="w-full max-w-xl rounded-2xl border border-border/60 bg-card p-5">
        <Textarea size="lg" resize="vertical" label="AI prompt" helperText="Be specific about the audience, output format, and constraints." placeholder="Generate a premium SaaS landing page section for..." />
      </div>
    </Preview>
  </Tab>

  <Tab value="Code">
    ```tsx title="prompt-textarea.tsx"
    import { Textarea } from "@pycolors/ui";

    export function PromptTextarea() {
      return (
        <div className="rounded-2xl border border-border/60 bg-card p-5">
          <Textarea
            size="lg"
            resize="vertical"
            label="AI prompt"
            helperText="Be specific about the audience, output format, and constraints."
            placeholder="Generate a premium SaaS landing page section for..."
          />
        </div>
      );
    }
    ```
  </Tab>
</Tabs>

### Usage patterns

<Steps>
  <Step>
    #### Use Textarea for longer answers

    Use Input for short values. Use Textarea when the user needs to provide context, explanation, or multi-line content.
  </Step>

  <Step>
    #### Keep labels explicit

    The label should describe the content expected from the user, not the UI element itself.
  </Step>

  <Step>
    #### Add helper text for complex fields

    Use helper text when the field needs examples, constraints, or formatting guidance.
  </Step>

  <Step>
    #### Validate with actionable errors

    Error messages should explain what to change, not just that the value is invalid.
  </Step>

  <Step>
    #### Choose resize intentionally

    Use vertical resize for flexible content. Use no resize for controlled surfaces like sheets and compact cards.
  </Step>
</Steps>

## Textarea vs Input

| Situation              | Use      |
| ---------------------- | -------- |
| Name, email, URL, slug | Input    |
| Search query           | Input    |
| Short title            | Input    |
| Feedback message       | Textarea |
| Product description    | Textarea |
| Notes or comments      | Textarea |
| AI prompt              | Textarea |

<Callout title="Decision rule">
  If the expected answer can fit naturally on one line, use Input. If the user needs to explain something, use Textarea.
</Callout>

## API

| Prop         | Type                                                | Default      | Description                                   |
| ------------ | --------------------------------------------------- | ------------ | --------------------------------------------- |
| `label`      | `string`                                            | —            | Accessible label displayed above the textarea |
| `helperText` | `string`                                            | —            | Supporting text shown when there is no error  |
| `error`      | `string`                                            | —            | Error text and validation styling             |
| `size`       | `"sm" \| "md" \| "lg"`                              | `"md"`       | Design-system size                            |
| `resize`     | `"none" \| "vertical" \| horizontal" \| "both"`     | `"vertical"` | Native resize behavior                        |
| `className`  | `string`                                            | —            | Additional Tailwind classes                   |
| `...props`   | `React.TextareaHTMLAttributes<HTMLTextAreaElement>` | —            | Native textarea attributes                    |

### TypeScript types

```ts title="textarea-types.ts"
export type TextareaSize = "sm" | "md" | "lg";
export type TextareaResize = "none" | "vertical" | "horizontal" | "both";

export interface TextareaProps
  extends Omit<
      React.TextareaHTMLAttributes<HTMLTextAreaElement>,
      "size"
    >,
    VariantProps<typeof textareaVariants> {
  label?: string;
  helperText?: string;
  error?: string;
  size?: TextareaSize;
  resize?: TextareaResize;
}
```

### Accessibility

* `label` is connected to the textarea with `htmlFor`.
* A stable id is generated with `React.useId` when no id is provided.
* `helperText` is connected with `aria-describedby`.
* `error` is connected with `aria-errormessage`.
* `error` sets `aria-invalid`.
* `error` text has `role="alert"` and is announced live, even while the field is already focused.
* `required` sets `aria-required`.
* Do not rely on placeholder text as the only accessible description.

<Callout title="Accessibility rule">
  Every textarea should have a clear label. Helper text and error text should clarify the task, not replace the label.
</Callout>

## Prefer / avoid

<PreferAvoid
  prefer={[
  'visible labels',
  'clear helper text for complex inputs',
  'specific and actionable errors',
  'vertical resize for longer content',
  'textarea for explanation-heavy fields',
]}
  avoid={[
  'placeholder-only labels',
  'vague errors like “Invalid value”',
  'horizontal resize in responsive layouts',
  'using textarea for short one-line values',
  'asking for too much text without guidance',
]}
/>

## Common questions

<Accordions type="single">
  <Accordion title="Should Textarea use a visible label?">
    Yes. A visible label improves usability and accessibility. Placeholder text should only provide examples or hints.
  </Accordion>

  <Accordion title="Should I use Textarea for titles?">
    Usually no. Use Input for short titles, names, slugs, emails, and URLs.
  </Accordion>

  <Accordion title="Can Textarea be used inside Sheet or Dialog?">
    Yes. It works well for comments, notes, and feedback forms. Use `resize="none"` if resizing would break the overlay layout.
  </Accordion>

  <Accordion title="Should helper text remain visible when there is an error?">
    In this component, error text replaces helper text to keep the field feedback focused. Put permanent requirements in the label or surrounding copy if they must remain visible.
  </Accordion>
</Accordions>

## Related

<DocsLinks
  variant="list"
  tone="platform"
  items={[
  {
    title: 'Input',
    href: '/docs/ui/input',
    description:
      'Use Input for short one-line values such as names, URLs, and search queries.',
    icon: FormInput,
  },
  {
    title: 'Button',
    href: '/docs/ui/button',
    description:
      'Pair Textarea with clear submit, save, or feedback actions.',
    icon: MousePointerClick,
  },
  {
    title: 'Sheet',
    href: '/docs/ui/sheet',
    description:
      'Use Textarea inside side panels for notes, filters, and contextual editing.',
    icon: PanelsTopLeft,
  },
  {
    title: 'Forms guide',
    href: '/docs/guides/forms',
    description:
      'Learn how to compose labels, helper text, validation, and actions.',
    icon: ClipboardCheck,
  },
]}
/>