Input

A text input that works with Field, with an optional character counter and screen reader announcements.

Username

<ui:input.root class="max-w-74" autocomplete="username">
    <ui:input.label>Username</ui:input.label>
    <ui:input.input />
</ui:input.root>

Features

Works standalone or directly inside ui:field.root, no field.control wrapper
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:input.root>
    <primitives:input.label />
    <primitives:input.input />
    <primitives:input.wordCount />
</primitives:input.root>

Installation

typo3 ui:add input

Read more about installing Components and Primitives.

Examples

With field

Nest ui:input.root directly inside ui:field.root. The input takes name, disabled, required, invalid and aria-describedby from the field. Label it with the primitive's own input.label, which targets the input for you. The demo is a required email field with helper and error text.

We'll only use this to send your confirmation.

<ui:field.root class="max-w-74" name="email" required="{true}">
    <ui:input.root type="email" autocomplete="email" placeholder="you@example.com">
        <ui:input.label>Email</ui:input.label>
        <ui:input.input />
    </ui:input.root>
    <ui:field.helperText>We'll only use this to send your confirmation.</ui:field.helperText>
    <ui:field.errorText />
</ui:field.root>

With word count

Pass maxLength and place the wordCount part anywhere inside input.root. The bio in the demo counts up to 140 characters.

Bio 0 / 140 characters

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

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 meta description that starts over its limit.

Meta description Characters over the limit: 15

<ui:input.root class="max-w-74" maxLength="120" maxLengthBehavior="{f:constant(name: 'Jramke\FluidPrimitives\Enum\MaxLengthBehavior::Warn')}" defaultValue="Handmade ceramics from our studio in Leipzig. Every piece ships within three working days, packed without any plastic and made to last.">
    <ui:input.label>Meta description</ui:input.label>
    <ui:input.input />
    <ui:input.wordCount />
</ui:input.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". 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.

Display name 0 / 20 characters

<ui:field.root class="max-w-74" name="displayName">
    <ui:input.root maxLength="20" maxLengthBehavior="{f:constant(name: 'Jramke\FluidPrimitives\Enum\MaxLengthBehavior::Invalid')}" placeholder="Pick a display name">
        <ui:input.label>Display name</ui:input.label>
        <ui:input.input />
        <ui:input.wordCount />
    </ui:input.root>
    <ui:field.errorText match="{f:constant(name: 'Jramke\FluidPrimitives\Enum\ValidityMatch::TooLong')}">Use 20 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 input. A function can't be set from the template, so pass transform where you create Input in your own entry file. Type a coupon code in lowercase and it turns uppercase as you type.

Coupon Code

<ui:exposeToClient />

<ui:input.root class="max-w-74" autoMount="{false}" rootId="transform-example-input" placeholder="e.g. summer24">
    <ui:input.label>Coupon Code</ui:input.label>
    <ui:input.input />
</ui:input.root>

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

import { mount, mountAll } from 'fluid-primitives';
import { Input } from 'fluid-primitives/input';

mountAll('ui:transformExample', () => {
    mount('ui:input', 'transform-example-input', ({ props }) => {
        const input = new Input({
            ...props,
            transform: value => value.toUpperCase(),
        });
        input.init();
        return input;
    });
});

API Reference

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

input.root

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

Name	Description	Required	Default
`type`	`string` The HTML input type attribute, e.g. text, email, password, search, tel, url.	No	'text'
`placeholder`	`string` Placeholder text shown when the input is empty.	No	-
`autocomplete`	`string` Hints for browser autofill, e.g. email, tel, given-name, 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 input. Useful for form submission. Inherited from a surrounding field when available.	No	-
`disabled`	`boolean` Whether the input is disabled. Inherited from a surrounding field when available.	No	-
`invalid`	`boolean` Whether the input value is invalid. Inherited from a surrounding field when available.	No	-
`required`	`boolean` Whether the input is required. Inherited from a surrounding field when available.	No	-
`readOnly`	`boolean` Whether the input is readonly. Inherited from a surrounding field when available.	No	-
`defaultValue`	`string` The initial value of the input when rendered. Use when you don't need to control the value of the input. 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
`pattern`	`string` A regular expression the input's value is checked against on form submission.	No	-
`inputMode`	`Enum\InputMode` Hints at the type of data that might be entered by the user and the keyboard shown on mobile devices, e.g. numeric, email, tel.	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`.

input.label

Labels the input. 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

input.input

The editable input. Renders an <input> 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

input.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 input.	-
`ids`	`Record<string, string> \| undefined` The ids of the parts other elements reference: `input` (the `for` of its label) and `wordCount`.	-
`name`	`string \| undefined` The name of the input, as it is submitted with the form. Taken from the closest field.	-
`disabled`	`boolean \| undefined` Whether the input is disabled. Taken from the closest field.	-
`readOnly`	`boolean \| undefined` Whether the input is read-only. Taken from the closest field.	-
`required`	`boolean \| undefined` Whether the input is required. Taken from the closest field.	-
`invalid`	`boolean \| undefined` Whether the input is invalid. Taken from the closest field.	-
`defaultValue`	`string \| undefined` The initial value of the input.	-
`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"
`pattern`	`string \| undefined` A regular expression the value has to match.	-
`inputMode`	`JSX.HTMLAttributes<HTMLInputElement>['inputMode'] \| undefined` The kind of virtual keyboard to show on devices that have one.	-
`translations`	`InputTranslations \| undefined` The localized texts of the input.	-
`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 input, e.g. uppercased or digits only. The cursor position is kept. It cannot be set from a Fluid template, only by constructing `Input` 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 input.
`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 input is disabled.
`readOnly`	`boolean`	Whether the input is read-only.
`required`	`boolean`	Whether the input is required.
`invalid`	`boolean`	Whether the input is invalid.
`name`	`string \| undefined`	The name of the input.
`maxLength`	`number \| undefined`	The most characters allowed.