Textarea

View as Markdown

A multi-line text input that works with Field, with an optional character counter, 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 directly inside ui:field.root, no field.control wrapper
The ui copy grows with its content through CSS field-sizing: content, see the MDN docs for browser support
Optional submitOn prop to submit the nearest form on Enter or Cmd/Ctrl+Enter
Optional transform callback to sanitize or reformat the value while typing, the cursor position is kept
Optional wordCount part with a translatable "42 / 250 characters" counter, driven by maxLength
maxLengthBehavior lets a paste arrive whole and shows that it is over maxLength, instead of cutting it off
Counter updates are announced to screen readers, debounced by announceDebounce (600 ms by default). Pass announce="{false}" to turn this 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. The textarea takes name, disabled, required, invalid and aria-describedby from the field. Label it with the primitive's own textarea.label, which targets the textarea for you. The demo is a required bio field with helper and error text.

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 place the wordCount part anywhere inside textarea.root. The bio in the demo counts up to 280 characters.

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

Set submitOn="{f:constant(name: 'Jramke\FluidPrimitives\Enum\TextareaSubmitOn::ModEnter')}" to submit the surrounding form with Cmd/Ctrl+Enter while plain Enter inserts a newline. TextareaSubmitOn::Enter submits with plain Enter and inserts a newline with Shift+Enter. Wrap the textarea in ui:form.root or a native <form>: submitOn calls its requestSubmit(). Press Cmd/Ctrl+Enter in the demo to submit it.

<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');
    });
});

Allow typing past the limit

Set maxLengthBehavior="{f:constant(name: 'Jramke\FluidPrimitives\Enum\MaxLengthBehavior::Warn')}" to keep maxLength as a target instead of a wall. The browser cuts nothing off, the count switches to "Characters over the limit: 6" and the parts carry data-over-limit, next to data-at-limit for exactly maxLength characters and data-max-length-behavior to style warn apart from invalid. The form still submits. The demo is a product review that starts over its limit.

Product review Characters over the limit: 16

<ui:textarea.root class="max-w-74" maxLength="140" maxLengthBehavior="{f:constant(name: 'Jramke\FluidPrimitives\Enum\MaxLengthBehavior::Warn')}" defaultValue="Arrived a day early and the glaze looks even better in person. The mug keeps my coffee warm for much longer than I expected, and it survived the dishwasher.">
    <ui:textarea.label>Product review</ui:textarea.label>
    <ui:textarea.textarea />
    <ui:textarea.wordCount />
</ui:textarea.root>

Enforce the limit that matters on the server. To accept a few characters over, give the template a lower maxLength than the validator, for example StringLength(maximum: 210) behind maxLength="200". A textarea submits each line break as two characters, so leave a few characters of room. The count is the one of the browser's maxlength, in UTF-16 units, so an emoji counts twice. mb_strlen and a VARCHAR(n) column count it once, so the count is never lower than the server's.

Reject text past the limit

MaxLengthBehavior::Invalid works like Warn and also makes the surrounding field invalid with the tooLong validity, so a form does not submit until the text fits. The error shows when the user leaves the field, like any other constraint. Give ui:field.errorText a match of ValidityMatch::TooLong for your own message. Type past the limit in the demo and tab out.

Message 0 / 200 characters

<ui:field.root class="max-w-74" name="message">
    <ui:textarea.root maxLength="200" maxLengthBehavior="{f:constant(name: 'Jramke\FluidPrimitives\Enum\MaxLengthBehavior::Invalid')}" placeholder="How can we help?">
        <ui:textarea.label>Message</ui:textarea.label>
        <ui:textarea.textarea />
        <ui:textarea.wordCount />
    </ui:textarea.root>
    <ui:field.errorText match="{f:constant(name: 'Jramke\FluidPrimitives\Enum\ValidityMatch::TooLong')}">Shorten your message to 200 characters or fewer.</ui:field.errorText>
</ui:field.root>

With a transform callback

transform runs on every input event and returns the value to write back to the textarea. A function can't be set from the template, so pass transform where you create Textarea in your own entry file. Type in lowercase and it turns uppercase 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, see `maxLengthBehavior` for what happens beyond it. Also drives the wordCount part, e.g. '42 / 250 characters'.	No	-
`maxLengthBehavior`	`Enum\MaxLengthBehavior` What happens when the value is longer than `maxLength`. - `block`: The browser stops the typing and cuts a paste off at the limit. - `warn`: Typing and pasting past the limit is allowed, the word count and `data-over-limit` show it, the form still submits. - `invalid`: Like `warn`, and a surrounding field also becomes invalid with the `tooLong` validity, so the form does not submit.	No	Block
`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 strings, `wordCount` and `wordCountOver`, with `%count%`, `%max%` and `%over%` placeholders. In a client script they are functions of `{ count, max, over }`. 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
`data-max-length-behavior`	The `maxLengthBehavior` while there is a `maxLength`: `block`, `warn` or `invalid`. Style the over-limit state of `warn` and `invalid` apart. One of: "invalid", "block", "warn".
`data-at-limit`	Present while the value is exactly `maxLength` characters long.
`data-over-limit`	Present while the value is longer than `maxLength` and `maxLengthBehavior` is not `block`.

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-max-length-behavior`	The `maxLengthBehavior` while there is a `maxLength`: `block`, `warn` or `invalid`. Style the over-limit state of `warn` and `invalid` apart. One of: "invalid", "block", "warn".
`data-at-limit`	Present while the value is exactly `maxLength` characters long.
`data-over-limit`	Present while the value is longer than `maxLength` and `maxLengthBehavior` is not `block`.
`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	-

Rendered data attributes

Attribute	Description
`data-max-length-behavior`	The `maxLengthBehavior` while there is a `maxLength`: `block`, `warn` or `invalid`. Style the over-limit state of `warn` and `invalid` apart. One of: "invalid", "block", "warn".
`data-at-limit`	Present while the value is exactly `maxLength` characters long.
`data-over-limit`	Present while the value is longer than `maxLength` and `maxLengthBehavior` is not `block`.

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`.	-
`maxLengthBehavior`	`MaxLengthBehavior \| undefined` What happens when the value is longer than `maxLength`. `block` stops the typing and cuts a paste off, `warn` allows both and only shows that the value is over the limit, `invalid` does the same and makes a surrounding field invalid (`tooLong`).	"block"
`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.
`over`	`number`	The number of characters over `maxLength`. It is always `0` for `maxLengthBehavior="block"`.
`atLimit`	`boolean`	Whether the value is exactly `maxLength` characters long.
`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.