Input

A text input component that works with Field, with optional word count 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 nested directly inside ui:field.root - no field.control wrapper needed
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: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 - it inherits name, disabled, required, invalid and aria-describedby automatically, the same way ui:select/ui:numberInput do. Use the primitive's own label part (nested inside root) rather than field.label - it targets the right control automatically.

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 add the wordCount part wherever you want it - it doesn't need to be a direct sibling of input.

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>

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 input, 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 Input yourself in a custom entry file, rather than as a Fluid prop. Type lowercase below - it's uppercased 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. Also drives the wordCount part, e.g. '42 / 250 characters'.	No	-
`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 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

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-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	-

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`.	-
`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.
`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.

Input

Features

Anatomy

Installation

Examples

With Field

With Word Count

With a Transform Callback

API Reference

input.root

Rendered data attributes

input.label

Rendered data attributes

input.input

Rendered data attributes

input.wordCount

Machine options

Machine JavaScript API

On this page