Textarea

View as Markdown

A multi-line text input that works with Field, with optional word count, screen reader announcements, and submit-on-Enter.

View Source

Message

<ui:textarea.root class="max-w-74" placeholder="Type your message here...">
    <ui:textarea.label>Message</ui:textarea.label>
    <ui:textarea.textarea />
</ui:textarea.root>

Features

Works standalone or nested directly inside ui:field.root - no field.control wrapper needed
Auto-resizes to fit its content via CSS field-sizing: content - no @zag-js/auto-resize or JS involved, see the MDN docs for browser support
Optional submitOn prop to submit the nearest form on Enter or Cmd/Ctrl+Enter instead of inserting a newline
Optional transform callback to sanitize/reformat the value as the user types, with cursor position preserved
Optional wordCount part rendering a translatable "42 / 250 characters" style counter, driven by maxLength
Word count updates are announced to screen readers by default through the page's shared live region, debounced so it doesn't spam assistive tech on every keystroke - pass announce="{false}" to turn it off

Anatomy

<primitives:textarea.root>
    <primitives:textarea.label />
    <primitives:textarea.textarea />
    <primitives:textarea.wordCount />
</primitives:textarea.root>

Installation

typo3 ui:add textarea

Read more about installing Components and Primitives.

Examples

With Field

Nest ui:textarea.root directly inside ui:field.root - it inherits name, disabled, required, invalid and aria-describedby automatically, the same way ui:input/ui:select do. Use the primitive's own label part (nested inside root) rather than field.label - it targets the right control automatically.

Bio

Shown on your public profile.

<ui:field.root class="max-w-74" name="bio" required="{true}">
    <ui:textarea.root placeholder="Tell us about yourself">
        <ui:textarea.label>Bio</ui:textarea.label>
        <ui:textarea.textarea />
    </ui:textarea.root>
    <ui:field.helperText>Shown on your public profile.</ui:field.helperText>
    <ui:field.errorText />
</ui:field.root>

With Word Count

Pass maxLength and add the wordCount part wherever you want it - it doesn't need to be a direct sibling of textarea.

Bio 0 / 280 characters

<ui:textarea.root class="max-w-74" maxLength="280" placeholder="Tell us about yourself">
    <ui:textarea.label>Bio</ui:textarea.label>
    <ui:textarea.textarea />
    <ui:textarea.wordCount />
</ui:textarea.root>

Submit on Enter

Pass submitOn="{f:constant(name: 'Jramke\FluidPrimitives\Enum\TextareaSubmitOn::ModEnter')}" to submit the nearest <form> on Cmd/Ctrl+Enter instead of inserting a newline - plain Enter still inserts a newline. Use TextareaSubmitOn::Enter for the opposite: plain Enter submits, Shift+Enter inserts a newline. Wrap the textarea in ui:form.root (or any native <form>) for the submit to actually go anywhere - submitOn just calls closest('form')?.requestSubmit().

<ui:exposeToClient />

<form {ui:ref(name: 'form' )} class="w-full max-w-74">
    <ui:textarea.root submitOn="{f:constant(name: 'Jramke\FluidPrimitives\Enum\TextareaSubmitOn::ModEnter')}" placeholder="Press Cmd/Ctrl+Enter to submit...">
        <ui:textarea.label>Message</ui:textarea.label>
        <ui:textarea.textarea rows="3" />
    </ui:textarea.root>
</form>

<vite:asset entry="EXT:docs/Resources/Private/Components/TextareaSubmitOnEnterExample/TextareaSubmitOnEnterExample.entry.ts" />

import { mountAll } from 'fluid-primitives';

mountAll('ui:textareaSubmitOnEnterExample', ({ createHydrator }) => {
    const hydrator = createHydrator();
    const form = hydrator.query<HTMLFormElement>('form');
    if (!form) return;

    form.addEventListener('submit', event => {
        event.preventDefault();
        alert('Form submitted');
    });
});

With a Transform Callback

transform runs on every native input event, before the value is committed - return the value that should actually be written back to the textarea, with cursor position preserved across the rewrite. Because a real function can't cross the PHP → client JSON boundary, this can only be set by constructing Textarea yourself in a custom entry file, rather than as a Fluid prop. Type lowercase below - it's uppercased as you type:

Shout Mode

<ui:exposeToClient />

<ui:textarea.root class="max-w-74" autoMount="{false}" rootId="transform-example-textarea" placeholder="Type in lowercase...">
    <ui:textarea.label>Shout Mode</ui:textarea.label>
    <ui:textarea.textarea />
</ui:textarea.root>

<vite:asset entry="EXT:docs/Resources/Private/Components/TextareaTransformExample/TextareaTransformExample.entry.ts" />

import { mount, mountAll } from 'fluid-primitives';
import { Textarea } from 'fluid-primitives/textarea';

mountAll('ui:textareaTransformExample', () => {
    mount('ui:textarea', 'transform-example-textarea', ({ props }) => {
        const textarea = new Textarea({
            ...props,
            transform: value => value.toUpperCase(),
        });

        textarea.init();
        return textarea;
    });
});

API Reference

The following tables cover the available props of the Fluid Primitives.

textarea.root

Provides shared textarea state and wraps all related parts. Renders a <div> element.

Name	Description	Required	Default
`placeholder`	`string` Placeholder text shown when the textarea is empty.	No	-
`autocomplete`	`string` Hints for browser autofill, e.g. street-address. See the [HTML spec](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill) for the full list of tokens.	No	-
`name`	`string` The name attribute of the textarea. Useful for form submission. Inherited from a surrounding field when available.	No	-
`disabled`	`boolean` Whether the textarea is disabled. Inherited from a surrounding field when available.	No	-
`invalid`	`boolean` Whether the textarea value is invalid. Inherited from a surrounding field when available.	No	-
`required`	`boolean` Whether the textarea is required. Inherited from a surrounding field when available.	No	-
`readOnly`	`boolean` Whether the textarea is readonly. Inherited from a surrounding field when available.	No	-
`defaultValue`	`string` The initial value of the textarea when rendered. Use when you don't need to control the value of the textarea. Inherited from a surrounding field when available.	No	''
`maxLength`	`integer` The maximum number of characters allowed. Also drives the wordCount part, e.g. '42 / 250 characters'.	No	-
`rows`	`integer` The number of visible text lines.	No	-
`submitOn`	`Enum\TextareaSubmitOn` Submits the nearest form on a keypress instead of inserting a newline: Enter submits on plain Enter (Shift+Enter still inserts a newline), ModEnter submits on Cmd/Ctrl+Enter (plain Enter always inserts a newline). Unset (the default) never intercepts Enter.	No	-
`translations`	`array` Specifies the localized word count string. Use `f:translate` for per-template localization overrides when needed.	No	-
`announce`	`boolean` Whether the word count is announced to assistive tech as the user types. Set to false to stay silent.	No	true
`announceDebounce`	`integer` Milliseconds to debounce word count announcements by, so rapid typing doesn't spam assistive tech. Set to 0 to announce every change immediately.	No	600
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`rootId`	`string` The root ID of the component, used for hydration and identification.	No	-
`ids`	`array` The IDs of of the component parts for composition.	No	[]
`autoMount`	`boolean` Whether the client initializes the component on its own. Set it to false to mount it yourself with `mount()`	No	true
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-invalid`	Present when invalid
`data-disabled`	Present when disabled
`data-readonly`	Present when read-only

textarea.label

Labels the textarea. Renders a <label> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-invalid`	Present when invalid
`data-disabled`	Present when disabled
`data-required`	Present when required

textarea.textarea

The editable textarea. Renders a <textarea> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-invalid`	Present when invalid
`data-disabled`	Present when disabled
`data-readonly`	Present when read-only

textarea.wordCount

Displays the character count, e.g. '42 / 250 characters'. Renders a <span> element.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Machine options

Name	Description	Default
`id`	`string` The unique identifier of the textarea.	-
`ids`	`Record<string, string> \| undefined` The ids of the parts other elements reference: `textarea` (the `for` of its label) and `wordCount`.	-
`name`	`string \| undefined` The name of the textarea, as it is submitted with the form. Taken from the closest field.	-
`disabled`	`boolean \| undefined` Whether the textarea is disabled. Taken from the closest field.	-
`readOnly`	`boolean \| undefined` Whether the textarea is read-only. Taken from the closest field.	-
`required`	`boolean \| undefined` Whether the textarea is required. Taken from the closest field.	-
`invalid`	`boolean \| undefined` Whether the textarea is invalid. Taken from the closest field.	-
`defaultValue`	`string \| undefined` The initial value of the textarea.	-
`maxLength`	`number \| undefined` The most characters allowed. It also drives the word count, e.g. `42 / 250 characters`.	-
`rows`	`number \| undefined` The number of visible lines.	-
`submitOn`	`TextareaSubmitOn \| undefined` Submits the closest `<form>` on a keypress instead of inserting a newline. `'enter'` submits on Enter, Shift+Enter still inserts a newline. `'mod+enter'` submits on Cmd or Ctrl+Enter, Enter always inserts a newline. By default Enter is never intercepted.	-
`translations`	`TextareaTranslations \| undefined` The localized texts of the textarea.	-
`announce`	`boolean \| undefined` Whether the word count is announced to assistive tech. Set to `false` to stay silent.	true
`announceDebounce`	`number \| undefined` Milliseconds to debounce word count announcements by, so rapid typing doesn't spam assistive tech on every keystroke. Set to 0 to announce every change immediately.	600
`transform`	`((value: string, event: Event) => string) \| undefined` Runs on every native `input` event, before the value is committed. Return the value to write back to the textarea, e.g. trimmed. The cursor position is kept. It cannot be set from a Fluid template, only by constructing `Textarea` in your own entry file.	-
`onValueChange`	`((details: { value: string }) => void) \| undefined` Called when the value changes.	-

Machine JavaScript API

Name	Type	Description
`value`	`string`	The current value of the textarea.
`count`	`number`	The number of characters in the value.
`countText`	`string \| null`	The word count text, e.g. `42 / 250 characters`. `null` without `maxLength` or when the text is turned off.
`disabled`	`boolean`	Whether the textarea is disabled.
`readOnly`	`boolean`	Whether the textarea is read-only.
`required`	`boolean`	Whether the textarea is required.
`invalid`	`boolean`	Whether the textarea is invalid.
`name`	`string \| undefined`	The name of the textarea.
`maxLength`	`number \| undefined`	The most characters allowed.

Textarea

Features

Anatomy

Installation

Examples

With Field

With Word Count

Submit on Enter

With a Transform Callback

API Reference

textarea.root

Rendered data attributes

textarea.label

Rendered data attributes

textarea.textarea

Rendered data attributes

textarea.wordCount

Machine options

Machine JavaScript API

On this page