Input

A text input component that works with Field, with optional word count and live-region announcements.

Username

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

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

mountAll('input', ({ props }) => {
    const input = new Input(props);
    input.init();
    return input;
});

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
Optional liveRegion part that announces word count updates to screen readers via @zag-js/live-region, debounced so it doesn't spam assistive tech on every keystroke

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.description>We'll only use this to send your confirmation.</ui:field.description>
    <ui:field.error />
</ui:field.root>

With Word Count

Pass maxLength and add the wordCount/liveRegion parts wherever you want them - they don't need to be direct siblings 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.liveRegion />
</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" controlled="{true}" 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('transformExample', () => {
    mount('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`	`string` 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. Set the wordCount entry to false to disable the wordCount part and live-region announcements entirely. Use `f:translate` for per-template localization overrides when needed.	No	-
`announceDebounce`	`integer` Milliseconds to debounce word count live-region announcements by, so rapid typing doesn't spam assistive tech. Set to 0 to announce every change immediately.	No	600
`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	[]
`controlled`	`boolean` If true, the component is meant to be initialized manually inside another component	No	false
`class`	`string` The CSS class(es) to be applied to the component.	No	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]

input.label

Labels the input. Renders a <label> element.

Name	Description	Required	Default
`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	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]

input.input

The editable input. Renders an <input> element.

Name	Description	Required	Default
`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	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]

input.wordCount

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

Name	Description	Required	Default
`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	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]

input.liveRegion

Announces word count updates to assistive technology. Renders a <div> element.

Name	Description	Required	Default
`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	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]

Anatomy

<primitives:input.root>
    <primitives:input.label />
    <primitives:input.input />
    <primitives:input.wordCount />
    <primitives:input.liveRegion />
</primitives:input.root>