# Input

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

**Reference:** [View Source](https://github.com/jramke/fluid-primitives/tree/main/Resources/Private/Primitives/Input) · [Zag.js Docs](https://zagjs.com/components/react/input)

**Input.html**

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

**Input.ts**

```ts
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](https://zagjs.com), debounced so it doesn't spam assistive tech on every keystroke

## Installation

```bash
typo3 ui:add input
```

Or copy the files manually from GitHub (https://github.com/jramke/fluid-primitives.com/tree/main/packages/docs/Resources/Private/Registry/Input) into your project.

Read more about installing [Components and Primitives](/docs/core-concepts/primitives.md).

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

**Input.html**

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

**Input.html**

```html
<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:

**TransformExample.html**

```html
<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" />
```

**TransformExample.ts**

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

### input.root

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

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `type` | `string` | No | `'text'` | The HTML input type attribute, e.g. text, email, password, search, tel, url. |
| `placeholder` | `string` | No | `-` | Placeholder text shown when the input is empty. |
| `autocomplete` | `string` | No | `-` | 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. |
| `name` | `string` | No | `-` | The name attribute of the input. Useful for form submission. Inherited from a surrounding field when available. |
| `disabled` | `boolean` | No | `-` | Whether the input is disabled. Inherited from a surrounding field when available. |
| `invalid` | `boolean` | No | `-` | Whether the input value is invalid. Inherited from a surrounding field when available. |
| `required` | `boolean` | No | `-` | Whether the input is required. Inherited from a surrounding field when available. |
| `readOnly` | `boolean` | No | `-` | Whether the input is readonly. Inherited from a surrounding field when available. |
| `defaultValue` | `string` | No | `''` | 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. |
| `maxLength` | `integer` | No | `-` | The maximum number of characters allowed. Also drives the wordCount part, e.g. '42 / 250 characters'. |
| `pattern` | `string` | No | `-` | A regular expression the input's value is checked against on form submission. |
| `inputMode` | `string` | No | `-` | 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. |
| `translations` | `array` | No | `-` | 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. |
| `announceDebounce` | `integer` | No | `600` | 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. |
| `asChild` | `boolean` | No | `-` | If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. |
| `rootId` | `string` | No | `-` | The root ID of the component, used for hydration and identification. |
| `ids` | `array` | No | `[]` | The IDs of of the component parts for composition. |
| `controlled` | `boolean` | No | `false` | If true, the component is meant to be initialized manually inside another component |
| `class` | `string` | No | `-` | The CSS class(es) to be applied to the component. |
| `attributes` | `array` | No | `[]` | Additional attributes that should be rendered on the component where ui:attributes is used. |

### input.label

Labels the input. Renders a `<label>` element.

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

### input.input

The editable input. Renders an `<input>` element.

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

### input.wordCount

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

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

### input.liveRegion

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

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

## Anatomy

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