---
name: form-textarea-usage
description: >
Use after component-usage-ux when an app needs @techsio/ui-kit FormTextarea
for labeled multi-line text fields with Textarea, Label, StatusText,
validation status, help text, size, resize, required, and disabled props.
metadata:
component_version: "2.0.0"
type: "core"
library: "@techsio/ui-kit"
library_version: "0.3.2"
requires: "component-usage-ux textarea-usage 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/molecules/form-textarea.tsx libs/ui/src/atoms/textarea.tsx libs/ui/stories/molecules/form-textarea.stories.tsx libs/ui/src/molecules/form-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 FormTextarea Usage
Use FormTextarea for labeled long text fields such as notes, comments, and
descriptions.
## UX/UI guidelines
House rules come from the `ux-guidelines` skill (writing, formatting, states,
where actions and feedback live). This section applies them to `FormTextarea`.
**Use it when**
- Labelled free text longer than one line: notes, descriptions, comments, messages.
**Use something else when**
| Need | Use instead |
| --- | --- |
| Single-line text | FormInput |
| Rich formatted content | a rich-text editor |
**Do**
- Size the initial height to the expected length (3–5 lines for notes).
- Show a character counter only when there is a limit, and before the limit is reached.
- Explain where the text will appear (`Shown to the customer on the invoice.`).
**Don't**
- Use a textarea for structured data (addresses, lists) that deserves separate fields.
- Truncate saved text silently.
**Copy and states**
- Counter format `120 / 500`; over-limit error `Shorten the note to 500 characters.`
**Behaviour (from the UX spec)**
- Enter inserts a newline and never submits the form.
- `rows` sets the initial height, not a limit; a grown (resized) field must not cover the Save action or neighbouring fields.
- A rejection keeps the full text; never truncate silently.
**Figma → code**
| Figma | Code |
| --- | --- |
| `state=error` / `success` / `warning` | `validateStatus` |
| `state=disabled` | `disabled` |
| — (not in Figma) | `readOnly` |
| `required=true` | `required` |
Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Molecules/FormTextarea → UX guidelines*.
## Setup
```tsx
import { FormTextarea } from "@techsio/ui-kit/molecules/form-textarea"
```
Supported props:
```text
id: optional (stable unique ID generated when omitted or empty)
label: ReactNode
validateStatus: default | error | success | warning
helpText, showHelpTextIcon
requiredLabel: screen-reader text for the required state; pass a translation, "" omits it (default "(required)")
Textarea props: size, resize, readOnly (legacy readonly alias), required, disabled
```
## Core Patterns
### Use for complete textarea fields
Prefer FormTextarea over manual Label + Textarea + StatusText composition.
### Use validateStatus for field state
FormTextarea maps validation to Textarea variant and StatusText.
### Use Textarea resize API
Choose `resize="y" | "none" | "auto"` from layout needs, not custom classes.
## Common Mistakes
### HIGH Manual textarea field
Wrong:
```tsx