Cloaked Design SystemForms
Textarea
A controlled multiline form field with configurable rows, semantic surfaces, and native length constraints.
Implementation previewCOMPLETE STORYBOOK REFERENCE
9 storiesEvery example. In one place.
Explore every named example, including states, compositions, and theme variants.
Playground selectedOpen canvas
Example source
packages/design-system/src/components/forms/Textarea/Textarea.stories.tsxExport PlaygroundImplementation preview Local Storybook build 0.2.0-preview.1. Source specification status does not approve this runtime.
Stories + source JSON ↗Local specification source status: preview. Implementation preview pending sign-off.
A controlled multiline form field with configurable rows, semantic surfaces, and native length constraints.
Design-owned component contract ↗Version 0.2.0-preview.1 · Implementation preview pending sign-off
Implementation API 1 entry point · source-derived preview
Read the actual callable API and preserve its composition constraints. Each union branch is a complete alternative; props marked forbidden cannot be supplied.
import { Textarea } from '@cloakedinc/design-system';TextareaTextareaProps
packages/design-system/src/components/forms/Textarea/Textarea.tsx:44
| Prop | Type | Presence | Notes |
|---|---|---|---|
value | string | Required | Text to render. Controlled — the field shows this and nothing else. |
onChange | ((value: string) => void) | undefined | Optional | Called with the new text, not the change event. |
placeholder | string | undefined | Optional | Placeholder text. Defaults to `Enter details`. |
surface | TextareaSurface | undefined | Optional | Container background treatment.Source default: 'default' |
ariaLabel | string | undefined | Optional | Accessible name when no visible label is associated with the field. |
rows | number | undefined | Optional | Starting visible line count. Defaults to 4.Source default: 4 |
maxLength | number | undefined | Optional | Maximum number of characters accepted. |
name | string | undefined | Optional | Field name used when the surrounding form submits. |
onFocus | (() => void) | undefined | Optional | Called when the field takes focus. |
onBlur | (() => void) | undefined | Optional | Called when the field loses focus. |
className | string | undefined | Optional | |
testId | string | undefined | Optional | Test id on the `<textarea>` itself. |
id | string | undefined | Optional | DOM id the control renders, which the Field's label points at. |
disabled | boolean | undefined | Optional | Blocks interaction and dims the control. |
required | boolean | undefined | Optional | Marks the control required for native form semantics. |
invalid | boolean | undefined | Optional | Paints the invalid treatment and announces the control as invalid. A Field supplies this from its own `error`; set it directly only for a control with no Field around it. |
ariaDescribedBy | string | undefined | Optional | Ids of the helper or error copy describing the control, supplied by a parent Field. |
ariaLabelledBy | string | undefined | Optional | Id of the visible label naming the control, supplied by a parent Field. |
Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.
Overview
The multiline free-text control — token-styled to match Input but sized in rows.
When to use
Reach for Textarea when the answer is open-ended and can run past one line — notes, a
removal-request message, freeform feedback. Size the resting height with rows and cap entry
with maxLength.
- Editing a single-line value (a name, email, URL, short query)? Use
Input— it's the same visual treatment on one line. - Wrap it in
Fieldfor a label and helper/error copy. The Field'serrorturns this box red on its own;invalidis the escape hatch for a box with noFieldaround it.
In-app it backs the Playlist home feedback card (HomeFeedbackCard).
Component specification
$schema
../../../specs/component-spec.schema.jsonParts
- Id
- root
- Label
- Root
- Description
- Carries the caller's class around the multiline field.
- Id
- field
- Label
- Multiline field
- Description
- Native textarea that owns value, rows, form, focus, validation, and disabled semantics.
- Id
- placeholder
- Label
- Placeholder
- Description
- Temporary hint shown only while the field is empty.
Allowed Design Choices
- Variants
- Base
- Label
- Base
- Description
- One multiline treatment configured through the independent surface axis.
- Sizes
- Surfaces
- Default
- Label
- Default
- Description
- Uses the semantic input container.
- Raised
- Label
- Raised
- Description
- Uses the raised surface when placed directly on the page canvas.
Variants
- Id
- base
- Label
- Base
- Description
- Multiline native field with row-driven content capacity.
- Platforms
- ios
- android
- web
Sizes
None specifiedMeasurements
- Id
- minimum-height
- Label
- Minimum field height
- Kind
- exact
- Token
- --cds-size-120
- Value
- 120
- Unit
- px
- Applies To
- field
- Id
- vertical-padding
- Label
- Vertical field padding
- Kind
- exact
- Token
- --cds-space-20
- Value
- 20
- Unit
- px
- Applies To
- field
- Id
- horizontal-padding
- Label
- Horizontal field padding
- Kind
- exact
- Token
- --cds-space-24
- Value
- 24
- Unit
- px
- Applies To
- field
- Id
- corner-radius
- Label
- Field corner radius
- Kind
- exact
- Token
- --cds-radius-md
- Value
- 16
- Unit
- px
- Applies To
- field
Layout
- Alignment
- Text begins at the field's top-leading content inset; the enclosing Field's error message aligns below.
- Flow
- One multiline native field.
- Notes
- Rows may increase the resting height but never reduce it below the approved minimum.
- Use Field for a persistent label and helper copy.
Typography And Color
- Typography
- Label
- Field text
- Description
- Use the body ramp for entered text and placeholders.
- Token
- --cds-type-body-size
- Colors
- Label
- Default surface
- Description
- Use the semantic input container.
- Token
- --cds-input-container
- Label
- Raised surface
- Description
- Use the raised semantic surface.
- Token
- --cds-bg-surface
- Label
- Entered text
- Description
- Use primary text emphasis.
- Token
- --cds-text-primary
- Label
- Placeholder
- Description
- Use secondary text emphasis at full opacity.
- Token
- --cds-text-secondary
- Label
- Validation
- Description
- Use the solid danger role for invalid border and copy.
- Token
- --cds-status-danger-solid
States
- Id
- empty
- Label
- Empty
- Description
- Shows the explicit or default placeholder.
- Id
- filled
- Label
- Filled
- Description
- Shows controlled multiline content in primary text.
- Id
- focused
- Label
- Focused
- Description
- Accepts multiline editing. Draws no focus ring: the runtime is a touch-only WebView with no keyboard navigation, and the caret plus the on-screen keyboard already mark the active field.
- Id
- invalid
- Label
- Invalid
- Description
- Shows the danger border and invalid semantics. The corrective message belongs to the enclosing Field.
- Id
- disabled
- Label
- Disabled
- Description
- Blocks editing and dims the field.
Behavior
- Label
- Controlled editing
- Description
- Request each next string value while the parent owns rendered content.
- Label
- Rows
- Description
- Use the native rows value to express expected content capacity without replacing the minimum geometry.
- Label
- Length constraint
- Description
- Forward maxLength to native editing and form semantics.
- Label
- Resize
- Description
- Allow vertical web resizing only; never permit horizontal resizing to break the form width.
Accessibility
- Label
- Accessible name
- Description
- Associate a visible Field label or provide an accessible label for standalone usage.
- Label
- Validation
- Description
- Expose required, disabled, invalid, and described-by state through the native textarea.
- Label
- Placeholder
- Description
- Never use placeholder copy as the only persistent label for a complex form.
Content Adaptation
- Label
- Long content
- Description
- Wrap and vertically scroll long content while preserving the control width.
- Label
- Capacity cues
- Description
- Choose rows and maxLength from the expected answer rather than shrinking all multiline fields to one line.
Motion Haptics
- Motion
- Label
- Focus and validation
- Description
- Change focus and error indication without moving entered content.
- Haptics
- Label
- No intrinsic feedback
- Description
- Typing, focus, and validation do not request design-system haptics.
Platform Differences
- Platforms
- web
- Description
- Web exposes a vertical drag-resize affordance; iOS and Android rely on intrinsic text-view scrolling and layout.
- Rationale
- Pointer resizing is useful in Storybook and desktop web contexts but is not a native mobile interaction.