Textarea

Accessible, unstyled native textarea with controlled and uncontrolled state.


Package	`@vizejs/ui/textarea`
Maturity	stable
Own the source	`vize lib pull textarea`
Requires	controllable-state, id
Aliases	text area, multiline input, textarea field
Covers	HTML textarea, React Aria TextField, Reka UI Primitive

Usage

import { Textarea } from "@vizejs/ui/textarea";

Or copy the source into your project with vize lib pull textarea (see Source Distribution).

API

`Textarea`

Source: src/families/form/textarea/textarea-control.vue

Props

Prop	Type	Default	Description
`id`	`string \| null`	`undefined`	Consumer-owned control id. `null` and `undefined` select a deterministic fallback.
`name`	`string`	`undefined`	Native form field name.
`modelValue`	`string`	`undefined`	Controlled string value. `undefined` selects uncontrolled behavior.
`defaultValue`	`string`	`""`	Initial value for uncontrolled use and the value restored by form reset.
`disabled`	`boolean`	`false`	Disable editing, focus, and native form submission.
`readOnly`	`boolean`	`false`	Keep the textarea focusable while preventing user editing.
`required`	`boolean`	`false`	Mark the textarea as required for native constraint validation.
`placeholder`	`string`	`undefined`	Native placeholder text.
`autocomplete`	`string`	`undefined`	Native autocomplete hint.
`rows`	`number`	`undefined`	Suggested visible text row count.
`cols`	`number`	`undefined`	Suggested visible text column count.
`minlength`	`number`	`undefined`	Minimum accepted string length for native constraint validation.
`maxlength`	`number`	`undefined`	Maximum accepted string length for native constraint validation.
`spellcheck`	`boolean`	`undefined`	Native spellcheck preference.
`wrap`	`TextareaWrap`	`undefined`	Native line-wrapping policy.
`ariaLabel`	`string`	`undefined`	Accessible name when no label or `aria-labelledby` supplies one.
`ariaLabelledby`	`string`	`undefined`	Space-separated ids that label the textarea.
`ariaDescribedby`	`string`	`undefined`	Space-separated ids that describe the textarea.
`ariaErrormessage`	`string`	`undefined`	Id of the validation error message used while invalid.
`ariaInvalid`	`TextareaAriaInvalid`	`false`	Invalid state announced to assistive technology.

Events

Event	Payload	Description
`update:modelValue`	`[value: string]`	Fired when the value requests a new controlled string.
`input`	`[value: string, nativeEvent: Event]`	Fired after a native input event with the next string and native `Event`.
`change`	`[value: string, nativeEvent: Event]`	Fired after native change/commit with the current string and native `Event`.
`compositionStart`	`[value: string, nativeEvent: CompositionEvent]`	Fired when IME composition starts.
`compositionEnd`	`[value: string, nativeEvent: CompositionEvent]`	Fired when IME composition ends.

Exposed

Member	Type	Description
`composing`	`boolean`	Whether the native textarea is currently inside IME composition.
`value`	`string`	Current controlled or uncontrolled string value.
`focus`	`(options?: FocusOptions) => void`	Move focus to the native textarea.
`select`	`() => void`	Select the current native textarea text.
`setSelectionRange`	`( selectionStart: number, selectionEnd: number, direction?: "backward" \| "forward" \| "none", ) => void`	Set the native text selection range.
`setValue`	`(value: string) => boolean`	Request a value update and report whether it differs.
`reset`	`() => boolean`	Restore the current default value and report whether it changed.
`element`	`Readonly<ShallowRef<HTMLElement \| null>>`	Template ref to the rendered root element.

Behavior

Normative state × input → outcome table for textarea-control.vue (@vizejs/ui/textarea). Every row is proven by the named mounted-DOM test in src/families/form/textarea/textarea.test.ts; a row without a passing test is a contract violation.

#	State	Input	Outcome	Proven by
T1	editable, native	render	native `<textarea>`, deterministic `id`, accessible name, form attributes, line constraints, and invalid ARIA state	`renders a named native textarea with form and accessibility attributes`
T2	uncontrolled	native input / change	value follows the native element; emits `update:modelValue` before `input`, and emits `change` with the committed string	`uncontrolled textarea emits model before input and reports native change`
T3	controlled	native input	emits the request; the rendered value reverts to `modelValue` until the parent accepts the update	`controlled value wins until the parent accepts the request`
T4	uncontrolled, seeded	form reset	`defaultValue` seeds the initial value and form reset restores it without request-global state	`defaultValue seeds state and native form reset restores it`
T5	disabled	render / Tab	native `disabled`, `data-state="disabled"`, no sequential focus	`disabled and read-only textareas keep native availability semantics`
T6	read-only	render / Tab	native `readonly`, `data-state="readonly"`, remains focusable	`disabled and read-only textareas keep native availability semantics`
T7	composing	IME composition	`data-composing` and exposed `composing` track composition start/end while preserving the composed string	`tracks IME composition without losing the composed multiline value`
T8	uncontrolled	exposed methods	`setValue()` updates uncontrolled state, `select()` and `setSelectionRange()` update text selection, `focus()` focuses the field	`exposes value mutation, selection range, focus, and reset controls`

The subpath remains tree-shakable and retains no packaged CSS; those package contracts are pinned by distribution.test.ts, check:size, and check:tree-shaking.