> ## Documentation Index
> Fetch the complete documentation index at: https://clementineds.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Textarea Component: Multi-Line Text Input for React Apps

> The Clementine DS Textarea for multi-line text input — extends TextInput behavior with resizable height, autosize option, and consistent token binding.

`Textarea` is Clementine DS's multi-line free-text input. It wraps Mantine's `Textarea` component and re-exports it with Clementine token bindings applied through `ClementineDSProvider`. Every prop that Mantine's `Textarea` accepts is available — import from `@clementine-ds/ui`, not from `@mantine/core` directly.

> [!WARNING]
>
> **Draft** — `Textarea` is a Draft component. The component renders correctly and shares the same interaction-state model as `TextInput`, but the default resize behavior and character-counter strategy are still open decisions. Token values are not yet validated against the rendered output.

Use `Textarea` when you expect users to enter more than one line of plain text: comments, notes, descriptions, or free-form messages. For single-line input use [`TextInput`](https://clementineds.mintlify.site/components/text-input). For rich text, reach for a rich-text editor (not yet in this DS).

***

## When to use

* The expected input spans multiple lines — a comment, a bio, a product description, a support message.
* You want to give users a visible writing area that clearly signals "this field accepts long content."
* You need fixed row height with optional user resize, or auto-growing height that tracks content.
* The field needs a character counter displayed inside the input boundary.

## When not to use

* **Single-line values** — use `TextInput`. The extra vertical space of a `Textarea` creates a misleading affordance for short values.
* **Rich text with formatting** — a `Textarea` renders plain text only. Use a rich-text editor for Markdown, HTML, or formatted content.
* **Structured multi-part input** — if the user must fill in several distinct fields, use multiple `TextInput` components instead of one large `Textarea`.

***

## Usage

```tsx theme={null}
import { Textarea } from '@clementine-ds/ui';

// Basic with label and description
<Textarea
  label="Your message"
  placeholder="Write your message here…"
  description="We'll respond within one business day."
/>

// Required field
<Textarea
  label="Bio"
  placeholder="Tell us about yourself"
  required
/>

// Error state
<Textarea
  label="Notes"
  error="Notes must be at least 20 characters"
  value={notes}
  onChange={(e) => setNotes(e.target.value)}
/>

// Fixed rows with vertical resize enabled
<Textarea
  label="Description"
  placeholder="Describe the issue…"
  rows={4}
  resize="vertical"
/>

// Autosize — grows with content, capped at 8 rows
<Textarea
  label="Details"
  placeholder="Type as much as you need…"
  autosize
  minRows={3}
  maxRows={8}
/>

// Disabled
<Textarea
  label="Audit log"
  value="Read-only content here."
  disabled
/>
```

### Controlled usage

```tsx theme={null}
import { useState } from 'react';
import { Textarea } from '@clementine-ds/ui';

function CommentBox() {
  const [value, setValue] = useState('');

  return (
    <Textarea
      label="Comment"
      placeholder="Add a comment…"
      value={value}
      onChange={(event) => setValue(event.currentTarget.value)}
    />
  );
}
```

### Character counter with `bottomSection`

```tsx theme={null}
import { useState } from 'react';
import { Textarea, Text } from '@clementine-ds/ui';

function LimitedTextarea() {
  const maxLength = 500;
  const [value, setValue] = useState('');

  return (
    <Textarea
      label="Your message"
      placeholder="Type your message…"
      autosize
      minRows={4}
      value={value}
      onChange={(event) => setValue(event.currentTarget.value.slice(0, maxLength))}
      bottomSection={
        <Text size="xs" c="dimmed">
          {value.length}/{maxLength} characters
        </Text>
      }
    />
  );
}
```

### Uncontrolled usage with FormData

```tsx theme={null}
import { Textarea } from '@clementine-ds/ui';

function MessageForm() {
  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        const formData = new FormData(event.currentTarget);
        console.log('Message:', formData.get('message'));
      }}
    >
      <Textarea label="Message" name="message" rows={4} />
      <button type="submit">Send</button>
    </form>
  );
}
```

***

## Props

`TextareaProps` extends Mantine's `TextareaProps` directly — all Mantine props are available. The table below covers the props you'll use most often.

| Prop | Type | Default | Description |
| - | - | - | - |
| `label` | `React.ReactNode` | — | Renders a `<label>` element tied to the textarea via `for`/`id`. Always provide a label unless you set `aria-label`. |
| `description` | `React.ReactNode` | — | Helper text displayed below the label. Not shown when omitted. |
| `placeholder` | `string` | — | Native `placeholder` attribute. Supplement the label — don't replace it. |
| `error` | `React.ReactNode` | — | Error message rendered below the textarea. Triggers error border and text color. Pass `true` for error styling without a message. |
| `required` | `boolean` | — | Adds the `required` attribute and appends a red asterisk to the label. |
| `withAsterisk` | `boolean` | — | Shows the required asterisk next to the label without setting `required` on the element. |
| `disabled` | `boolean` | — | Sets the `disabled` attribute and applies disabled visual styles. |
| `value` | `string` | — | Controlled value. |
| `defaultValue` | `string` | — | Uncontrolled initial value. |
| `onChange` | `React.ChangeEventHandler<HTMLTextAreaElement>` | — | Called on every input change. Receives the native change event. |
| `rows` | `number` | — | Number of visible text rows. Sets the HTML `rows` attribute. |
| `autosize` | `boolean` | — | Enables auto-growing height. The textarea expands as the user types. |
| `minRows` | `number` | — | Minimum number of rows when `autosize` is enabled. Ignored otherwise. |
| `maxRows` | `number` | — | Maximum number of rows when `autosize` is enabled. Growth stops at this limit. |
| `resize` | `"none" \| "vertical" \| "both" \| "horizontal"` | `"none"` | Controls the CSS `resize` property. Set to `"vertical"` to allow user-controlled height resizing. |
| `bottomSection` | `React.ReactNode` | — | Content rendered inside the input border at the bottom — useful for character counters. |
| `bottomSectionProps` | `React.ComponentProps<"div">` | — | Extra props for the `bottomSection` wrapper element. |
| `loading` | `boolean` | — | Displays a loading spinner inside the textarea. |
| `loadingPosition` | `"left" \| "right"` | `"right"` | Controls which side the loading spinner appears on. |
| `leftSection` | `React.ReactNode` | — | Content rendered on the left side of the input. |
| `rightSection` | `React.ReactNode` | — | Content rendered on the right side of the input. |
| `leftSectionPointerEvents` | `React.CSSProperties["pointerEvents"]` | — | Set to `"none"` for decorative icons; `"all"` for interactive elements. |
| `rightSectionPointerEvents` | `React.CSSProperties["pointerEvents"]` | — | Same as `leftSectionPointerEvents` for the right side. |
| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"sm"` | Controls input height baseline, horizontal padding, and font size. |
| `radius` | `MantineRadius \| number` | — | Sets `border-radius`. Accepts theme radius keys or a raw CSS value. |
| `withErrorStyles` | `boolean` | — | Set to `false` to suppress error border/text color while still displaying the error message. |
| `inputWrapperOrder` | `("input" \| "label" \| "description" \| "error")[]` | — | Controls the render order and visibility of wrapper sub-elements. |
| `wrapperProps` | `WrapperProps` | — | Extra props spread onto the root wrapper element. |
| `name` | `string` | — | Native `name` attribute. Required when using uncontrolled forms with `FormData`. |

***

## Interaction states

`Textarea` shares the same interaction-state model as `TextInput`, with one fewer state — there is no `loading` spinner position difference.

| State | Trigger | Visual change |
| - | - | - |
| **Default** | Idle | `textarea.bg.default` background, `textarea.border.default` border |
| **Hover** | Mouse enters the textarea | `textarea.border.hover` border |
| **Focus** | Textarea receives keyboard or click focus | `textarea.border.focus` border + `textarea.ring` focus ring |
| **Filled** | Textarea has a non-empty value | Value rendered in `textarea.fg.value` color |
| **Disabled** | `disabled` prop is set | `textarea.bg.disabled` background, `textarea.fg.disabled` text, pointer events removed |
| **Error** | `error` prop is set | `textarea.border.error` border, error message in `feedback.error` color |

***

## Token contract

These design tokens cover `Textarea`. Tokens resolve through semantic aliases into the Clementine primitive palette.

| Token | Semantic alias |
| - | - |
| `textarea.bg.default` | `surface.elevated` |
| `textarea.bg.disabled` | `surface.subtle` |
| `textarea.fg.value` | `text.primary` |
| `textarea.fg.placeholder` | `text.secondary` |
| `textarea.fg.disabled` | `text.disabled` |
| `textarea.border.default` | `border.strong` |
| `textarea.border.focus` | `border.focus` |
| `textarea.border.error` | `feedback.error` |
| `textarea.ring` | `focus.ring` |
| `textarea.radius` | `radius.input` |

***

## Accessibility

* Always supply a visible `label` prop. Use `aria-label` only when no visible label is possible.
* On error, Mantine sets `aria-invalid="true"` on the textarea and associates the error element via `aria-describedby`. Verify this wiring in your form before shipping.
* Preserve user-controlled resize (`resize="vertical"`) unless the layout specifically cannot accommodate a taller textarea. Removing resize is a regression for users who enlarge text or have motor differences.
* The `required` prop sets the native `required` attribute, which screen readers announce. If you use `withAsterisk` for visual-only indication, also communicate the requirement through the `description` prop.
* `Textarea` supports standard keyboard interactions — `Tab` to focus, `Shift+Tab` to move backwards, and all standard text-editing keys inside the field.

***

## Draft status

`Textarea` carries a **Draft** status as of `clementine-ds@HEAD (2026-06-08)`. The following items are still open:

* **Resize default** — it is undecided whether the default behavior should be fixed rows with user resize, or auto-grow to content. Until resolved, use `resize="vertical"` or `autosize` explicitly rather than relying on any default.
* **Character counter strategy** — it is undecided whether a counter should appear automatically when `maxLength` is set, or only when `bottomSection` is used explicitly. Use `bottomSection` for now.
* Token values (`textarea.border.hover`, `textarea.fg.disabled`, `textarea.radius`) are defined in the spec but not yet validated against the rendered output.

Do not build production-critical token overrides against this component until these items are resolved.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.