---
name: textarea-usage
description: >
Use after component-usage-ux when an app needs @techsio/ui-kit Textarea for
multi-line text entry with valid variant, size, resize, readonly styling, and
token-first validation.
metadata:
component_version: "2.0.0"
type: "core"
library: "@techsio/ui-kit"
library_version: "0.3.2"
requires: "component-usage-ux app-token-overrides ux-guidelines"
resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md"
sources: ""
contributor_sources: "libs/ui/src/atoms/textarea.tsx libs/ui/src/tokens/components/atoms/_textarea.css libs/ui/stories/atoms/textarea.stories.tsx libs/ui/src/atoms/textarea.figma.ts"
audience: "consumer"
---
> Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory.
# @techsio/ui-kit Textarea Usage
Use Textarea for multi-line text entry. Use form molecules when a complete
label/help/error field abstraction exists for the current app context.
Business keeps error prompts neutral; validation stays on the border and associated
message. `--color-textarea-placeholder-danger` remains the error-prompt override.
## UX/UI guidelines
House rules come from the `ux-guidelines` skill (writing, formatting, states,
where actions and feedback live). This section applies them to `Textarea`.
**Use it when**
- Bare multi-line text controls in compositions that supply their own label (inline comment boxes, table editors).
**Use something else when**
| Need | Use instead |
| --- | --- |
| A labelled field | FormTextarea |
| Single-line text | Input |
**Do**
- Give it an accessible name.
- Auto-grow or size to the expected content; keep a sensible max height.
**Don't**
- Use placeholder as the label.
**Copy and states**
- Placeholder as an example (`Add a note for the courier…`).
**Behaviour (from the UX spec)**
- Enter inserts a newline and never submits; `rows` sets the initial height, not a length limit.
- `validateStatus="error" | "success" | "warning"` is presentation only; the rule lives in the form or app.
**Figma → code**
| Figma | Code |
| --- | --- |
| `validateStatus=default…warning`, `appearance=ghost` | same prop names and values |
| `state=disabled` | `disabled` |
| `state=readonly` | `readOnly` (not the legacy `readonly`) |
Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Atoms/Textarea → UX guidelines*.
## Setup
```tsx
import { Textarea } from "@techsio/ui-kit/atoms/textarea"
```
Supported component props:
```text
validateStatus: default | error | success | warning
appearance: outline | ghost
size: sm | md | lg
resize: none | y | x | both | auto
readOnly: boolean
readonly: boolean (legacy alias; prefer readOnly)
```
Use native `readOnly` for both immutable behavior and the full-contrast read-only surface. The legacy `readonly` alias remains supported; explicit `readOnly` takes precedence.
## Core Patterns
### Use variant for validation
```tsx
```
Do not style borders or placeholders inline for validation.
### Choose resize from layout
```text
y -> normal notes/comments
none -> fixed layout surfaces
auto -> content-sized field when supported by the target browser matrix
both/x -> rare, only when the product explicitly needs it
```
### Use readOnly for read-only styling
```tsx
```
Both spellings drive the native attribute and the same full-contrast visual treatment.
## Common Mistakes
### HIGH Native textarea
Wrong:
```tsx
```
Correct:
```tsx
```
Source: libs/ui/src/atoms/textarea.tsx
### HIGH Nonexistent validation variant
Wrong:
```tsx
```
Correct:
```tsx
```
Source: libs/ui/src/atoms/textarea.tsx
### HIGH Inline validation styling
Wrong:
```tsx
```
Correct:
```tsx
```
Source: libs/ui/src/tokens/components/atoms/_textarea.css
### MEDIUM Disabling a value that should remain copyable
Wrong:
```tsx
```
Correct:
```tsx
```
Use `readOnly` to preserve focus, selection, submission and normal contrast. Disabled takes precedence if both are set.
## Validation Commands
```sh
rg -n "