# Textarea

> Textarea captures multi-line input. It shares the Input size ramp and appearance props, resizes vertically, and never collapses below three lines.

Source: https://vaneui.com/docs/form-components/textarea

Import: `import { Textarea, Col, Field, Row } from "@vaneui/ui"`

Textarea is for comments, descriptions and other free-form text; a name, an email address or a number belongs in a single-line [Input](/docs/form-components/input). A Textarea inside a [Label](/docs/form-components/label) or a [Field](/docs/form-components/field) takes its size from that parent unless it sets its own.

## Basic usage

Textarea is an Input that wraps lines. It shares the Input size ramp and appearance props, and renders a real `<textarea>`, so every native attribute works.

```tsx demo
<Textarea placeholder="What changed in this release?" rows={4}/>
```

It resizes vertically by default and has a minimum height of three lines, so an empty textarea never collapses to a single row.

## Sizes

```tsx demo
<Col>
  <Textarea xs placeholder="xs"/>
  <Textarea sm placeholder="sm"/>
  <Textarea placeholder="md (default)"/>
  <Textarea lg placeholder="lg"/>
  <Textarea xl placeholder="xl"/>
</Col>
```

## Variants

Textarea is `outline` by default. Use `filled` for a solid background, and the appearance props for status colour.

```tsx demo
<Col>
  <Row flexWrap itemsStretch>
    <Textarea className="w-56" placeholder="Outline (default)"/>
    <Textarea className="w-56" success placeholder="Outline success"/>
    <Textarea className="w-56" danger placeholder="Outline danger"/>
  </Row>
  <Row flexWrap itemsStretch>
    <Textarea className="w-56" filled placeholder="Filled"/>
    <Textarea className="w-56" filled success placeholder="Filled success"/>
    <Textarea className="w-56" filled danger placeholder="Filled danger"/>
  </Row>
</Col>
```

## Shapes

```tsx demo
<Col>
  <Textarea rows={2} placeholder="Rounded, the default"/>
  <Textarea sharp rows={2} placeholder="Sharp"/>
  <Textarea pill rows={2} placeholder="Pill"/>
</Col>
```

## States

`invalid` paints a danger border and ring and emits `aria-invalid="true"`. Unlike `Input`, a Textarea shows no overlaid alert icon: a single-line field has one obvious place to put one, a box that grows does not. The border is therefore the only *visual* cue on its own, so pair `invalid` with a `Field` and let the `error` message carry the reason. It renders in danger text below the box and is linked with `aria-describedby`.

Note that the value itself never turns red. Colouring what the user typed hurts readability and says nothing about what is wrong.

```tsx demo
<Col>
  <Textarea placeholder="Default"/>
  <Field error="Tell us at least a sentence about what changed.">
    <Textarea defaultValue="Too short"/>
  </Field>
  <Textarea disabled defaultValue="Disabled"/>
  <Textarea readOnly defaultValue="Read only"/>
</Col>
```

## With a label and help text

```tsx demo
<Field label="Release notes" description="Markdown is supported.">
  <Textarea rows={3} placeholder="What changed?"/>
</Field>
```

## Props

| Prop | Category | Default | Description |
| --- | --- | --- | --- |
| `primary` | Appearance | yes | Primary color appearance (gray) |
| `accent` | Appearance |  | Accent color appearance (rose) |
| `secondary` | Appearance |  | Secondary color appearance (gray) |
| `tertiary` | Appearance |  | Tertiary color appearance |
| `success` | Appearance |  | Success color appearance (green) |
| `danger` | Appearance |  | Danger color appearance (red) |
| `warning` | Appearance |  | Warning color appearance (amber) |
| `info` | Appearance |  | Info color appearance (cyan) |
| `inheritAppearance` | Appearance |  | Inherit appearance from parent — suppresses own data-appearance/data-variant, uses parent's CSS variables |
| `disabled` | Disabled |  | Disable the component — reduces opacity, changes cursor to not-allowed, and prevents interaction |
| `flex1` | Flex |  | Take up remaining space (= `flex-1`, i.e. `flex: 1 1 0%`) |
| `flexAuto` | Flex |  | Grow but respect intrinsic size (= `flex-auto`, i.e. `flex: 1 1 auto`) |
| `flexNone` | Flex |  | Don't grow and don't shrink (= `flex-none`, i.e. `flex: none`) |
| `fontSans` | Font Family | yes | Sans-serif font family (default) — emits font-sans |
| `fontSerif` | Font Family |  | Serif font family — emits font-serif |
| `fontMono` | Font Family |  | Monospace font family — emits font-mono |
| `fontHeading` | Font Family |  | Heading font family (defaults to sans, customizable via --font-heading) — emits font-heading |
| `italic` | Font Style |  | Italic font style |
| `notItalic` | Font Style |  | Not italic (normal) font style |
| `fontThin` | Font Weight |  | Thin font weight (100) — emits font-thin |
| `fontExtralight` | Font Weight |  | Extra light font weight (200) — emits font-extralight |
| `fontLight` | Font Weight |  | Light font weight (300) — emits font-light |
| `fontNormal` | Font Weight | yes | Normal font weight (400) — emits font-normal |
| `fontMedium` | Font Weight |  | Medium font weight (500) — emits font-medium |
| `fontSemibold` | Font Weight |  | Semibold font weight (600) — emits font-semibold |
| `fontBold` | Font Weight |  | Bold font weight (700) — emits font-bold |
| `fontExtrabold` | Font Weight |  | Extra bold font weight (800) — emits font-extrabold |
| `fontBlack` | Font Weight |  | Black font weight (900) — emits font-black |
| `padding` | Padding | yes | Enable internal padding |
| `paddingX` | Padding |  | Enable only horizontal padding |
| `paddingY` | Padding |  | Enable only vertical padding |
| `noPadding` | Padding |  | Disable internal padding |
| `readOnly` | Read Only |  | Render the field read-only — mutes it (lighter than disabled) and sets a default cursor; the value stays selectable and submittable |
| `pill` | Shape |  | Fully rounded corners (circular) |
| `sharp` | Shape |  | No rounded corners (square) |
| `rounded` | Shape | yes | Medium rounded corners (default) |
| `noShrink` | Shrink |  | Prevent the flex item from shrinking below its content size (= `shrink-0`) |
| `xs` | Size |  | Extra small size |
| `sm` | Size |  | Small size |
| `md` | Size | yes | Medium size (default) |
| `lg` | Size |  | Large size |
| `xl` | Size |  | Extra large size |
| `textLeft` | Text Align |  | Align text to left (physical side, does not flip under RTL) |
| `textCenter` | Text Align |  | Align text to center |
| `textRight` | Text Align |  | Align text to right (physical side, does not flip under RTL) |
| `textJustify` | Text Align |  | Justify text |
| `textStart` | Text Align |  | Align text to the reading-direction start (left in LTR, right in RTL) |
| `textEnd` | Text Align |  | Align text to the reading-direction end (right in LTR, left in RTL) |
| `underline` | Text Decoration |  | Add underline decoration below text |
| `lineThrough` | Text Decoration |  | Add strikethrough/line-through decoration across text |
| `noUnderline` | Text Decoration |  | Remove ALL text-decoration — underline, line-through, and overline (text-decoration: none) |
| `overline` | Text Decoration |  | Add overline decoration above text |
| `uppercase` | Text Transform |  | Transform text to uppercase |
| `lowercase` | Text Transform |  | Transform text to lowercase |
| `capitalize` | Text Transform |  | Capitalize first letter of each word |
| `normalCase` | Text Transform |  | Normal text case (no transformation) |
| `truncate` | Truncate |  | Single line truncation with ellipsis |
| `lineClamp2` | Truncate |  | Truncate at 2 lines with ellipsis |
| `lineClamp3` | Truncate |  | Truncate at 3 lines with ellipsis |
| `lineClamp4` | Truncate |  | Truncate at 4 lines with ellipsis |
| `lineClamp5` | Truncate |  | Truncate at 5 lines with ellipsis |
| `noTruncate` | Truncate |  | Remove truncation |
| `invalid` | Validity |  | Mark the field invalid (red border/ring), layered over any appearance |
| `filled` | Variant |  | Filled variant - solid background with contrasting text color |
| `outline` | Variant | yes | Outline variant - transparent background with border and colored text (default) |
| `ghost` | Variant |  | Ghost variant - transparent background, no border, appearance-colored text, tinted hover background |

Layout and utility props (Border, Cursor, Display, Flex Direction, Focus Visible, Gap, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transition, Transparent, Whitespace, Width, Wrap) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).
