---
title: "Textarea"
description: "A multi-line text field with an optional count and error state."
category: "Form & Input"
slug: textarea
url: /components/textarea
since: "0.1.0"
status: "stable"
---

# Textarea

A multi-line text field with an optional count and error state.

## Import

```svelte
import { Textarea } from '@elluzion/iv-ui';
```

## Preview

A labelled textarea with helper text.

```svelte
<script lang="ts">
	import { Textarea } from '@elluzion/iv-ui';

	let notes = $state('');
</script>

<div class="field-row">
	<Textarea
		label="Release notes"
		placeholder="What changed in this deploy?"
		bind:value={notes}
		helper="Markdown is supported."
	/>
</div>

<style>
	.field-row {
		width: 100%;
		max-width: 420px;
	}
</style>
```

## Usage

- Bind `value` for two-way state; `oninput` receives the native event.
- `showCount` needs `maxlength` and renders the used and total characters.
- `resizable` controls which axes the user may drag.

## Examples

### Character count

`maxlength` and `showCount` expose the remaining budget.

```svelte
<script lang="ts">
	import { Textarea } from '@elluzion/iv-ui';

	let summary = $state('Tightened the focus ring and reduced the dialog entry by 40 ms.');
</script>

<div class="field-row">
	<Textarea label="Summary" maxlength={120} showCount bind:value={summary} />
</div>

<style>
	.field-row {
		width: 100%;
		max-width: 420px;
	}
</style>
```

### States

Error, disabled, and read-only treatments.

```svelte
<script lang="ts">
	import { Textarea } from '@elluzion/iv-ui';

	let description = $state('');
</script>

<div class="stack">
	<Textarea label="Description" bind:value={description} error="A description is required." />
	<Textarea label="Read only" value="Generated by the pipeline." readonly />
	<Textarea label="Disabled" value="Locked." disabled />
</div>

<style>
	.stack {
		display: flex;
		flex-direction: column;
		gap: var(--iv_spacing-lg);
		width: 100%;
		max-width: 420px;
	}
</style>
```

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` **bindable** | `string` | `''` | Current value. Bind with `bind:value`. |
| `placeholder` | `string` | `''` | Placeholder shown while the field is empty. |
| `disabled` | `boolean` | `false` | Disables interaction and applies the disabled treatment. |
| `readonly` | `boolean` | `false` | Prevents editing while keeping the value focusable and readable. |
| `required` | `boolean` | `false` | Marks the field as required. |
| `name` | `string` | `''` | Form field name submitted with the surrounding form. |
| `id` | `string` | `''` | Element id. A generated id is used when omitted. |
| `rows` | `number` | `4` | Visible number of text lines. |
| `maxlength` | `number` | — | Maximum number of characters. |
| `label` | `string` | `''` | Visible label for the control. |
| `error` | `string` | `''` | Error message. Switches the control to the error treatment. |
| `helper` | `string` | `''` | Helper text shown below the control. |
| `resizable` | `'none' \| 'vertical' \| 'horizontal' \| 'both'` | `'vertical'` | Which axes the user may resize. |
| `showCount` | `boolean` | `false` | Shows the character count when `maxlength` is set. |

`class`, `id`, `style`, `aria-*`, and `data-*` are forwarded through rest props.

### Events

| Event | Handler type | Description |
| --- | --- | --- |
| `input` | `(e: Event) => void` | Called on every keystroke with the native event. |
| `change` | `(e: Event) => void` | Called when the value changes; the new value is in `event.detail`. |
| `focus` | `(e: FocusEvent) => void` | Called when the control receives focus. |
| `blur` | `(e: FocusEvent) => void` | Called when the control loses focus. |
| `keydown` | `(e: KeyboardEvent) => void` | Called on keydown with the native keyboard event. |

The legacy `on:name` form is accepted for every event.

### Tokens used

`--iv_border` · `--iv_border-focus` · `--iv_border-hover` · `--iv_control-pad-x` · `--iv_control-pad-y` · `--iv_cursor` · `--iv_disabled-opacity` · `--iv_ease-in-out` · `--iv_error` · `--iv_error-surface` · `--iv_font-mono` · `--iv_font-ui` · `--iv_foreground` · `--iv_foreground-dim` · `--iv_leading-base` · `--iv_radius-sm` · `--iv_ring` · `--iv_ring-width` · `--iv_spacing-2xs` · `--iv_spacing-sm` · `--iv_surface-raised` · `--iv_text-base` · `--iv_text-label` · `--iv_text-sm` · `--iv_text-xs` · `--iv_transition-base`

See the [token reference](/foundations/tokens.md) for values.

### CSS hooks

`.iv-char-count` · `.iv-disabled` · `.iv-error-message` · `.iv-footer-row` · `.iv-has-error` · `.iv-helper-message` · `.iv-label` · `.iv-message` · `.iv-over-limit` · `.iv-required-mark` · `.iv-textarea-container` · `.iv-textarea-wrapper`

## Accessibility

| Keys | Action |
| --- | --- |
| `Tab` | Moves focus into the textarea. |
| `Enter` | Inserts a new line. |

- The label is associated with the textarea through a generated id, or pass `id`.
- Error text is linked through `aria-describedby`; the control gets `aria-invalid`.
- The character count is part of the described-by content when `showCount` is on.

## Related

- [Input](/components/input.md)
- [Field](/components/field.md)
- [NativeSelect](/components/native-select.md)
- [Article](/components/article.md)