Field

A form field wrapper that provides accessible labeling, error handling, and state management for form inputs.

Username

Choose a unique username for your account.

<ui:field.root name="username" required="{true}">
    <ui:field.label>Username</ui:field.label>
    <ui:field.control asChild="{true}">
        <ui:input type="text" autocomplete="username" />
    </ui:field.control>
    <ui:field.description>Choose a unique username for your account.</ui:field.description>
    <ui:field.error />
</ui:field.root>

import { mount } from 'fluid-primitives';
import { Field } from 'fluid-primitives/field';

mount('field', ({ props }) => {
	// @ts-expect-error
	const field = new Field(props);
	field.init();
	return field;
});

Features

Automatic label association with form controls
Error message display with proper ARIA attributes
Description text support for additional context
State management for disabled, required, readonly, and invalid states
Seamless integration with Form component for validation
Works with all form-related primitives (Checkbox, Select, RadioGroup, etc.) and native inputs

Installation

typo3 ui:add field

Read more about installing Components and Primitives.

Examples

Required Field

Mark a field as required.

Full Name

<ui:field.root name="name" required="{true}">
    <ui:field.label>Full Name</ui:field.label>
    <ui:field.control asChild="{true}">
        <ui:input type="text" />
    </ui:field.control>
    <ui:field.error />
</ui:field.root>

With Description

Add helpful description text below the input.

Password

Must be at least 8 characters long.

<ui:field.root name="password">
    <ui:field.label>Password</ui:field.label>
    <ui:field.control asChild="{true}">
        <ui:input type="password" />
    </ui:field.control>
    <ui:field.description>Must be at least 8 characters long.</ui:field.description>
    <ui:field.error />
</ui:field.root>

Invalid State

Indicate that the field has an error and display an error message.

Password

The password must be at least 8 characters long.

<ui:field.root name="password" required="{true}" invalid="{true}">
    <ui:field.label>Password</ui:field.label>
    <ui:field.control asChild="{true}">
        <ui:input type="password" />
    </ui:field.control>
    <ui:field.error>The password must be at least 8 characters long.</ui:field.error>
</ui:field.root>

Disabled Field

Disable the entire field.

Disabled Input

<ui:field.root name="readonly-value" disabled="{true}">
    <ui:field.label>Disabled Input</ui:field.label>
    <ui:field.control asChild="{true}">
        <ui:input type="text" value="Cannot be edited" />
    </ui:field.control>
</ui:field.root>

With Checkbox

Use with the Checkbox component.

I accept the terms and conditions

<ui:field.root name="terms" required="{true}">
    <ui:checkbox.root>
        <ui:checkbox.control />
        <ui:checkbox.label>I accept the terms and conditions</ui:checkbox.label>
    </ui:checkbox.root>
    <ui:field.error />
</ui:field.root>

API Reference

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

field.root

Provides shared field state for labels, descriptions, errors, and controls. Renders a <div> element.

Name	Description	Required	Default
`name`	`string` The unique field name used to associate labels, descriptions, errors, and form values.	Yes	-
`disabled`	`boolean` Whether the field is disabled.	No	-
`invalid`	`boolean` Whether the field is invalid.	No	-
`required`	`boolean` Whether the field is required.	No	-
`readOnly`	`boolean` Whether the field is read-only.	No	-
`defaultValue`	`mixed` The initial value that child controls can use when rendered inside the field.	No	-

field.label

Labels the associated form control. Renders a <label> element.

field.control

Wraps the slotted form control and wires up shared field attributes. Renders the element defined by the asChild prop.

field.description

Displays help or supporting text for the field. Renders a <div> element.

field.error

Displays validation error messages for the field. Renders a <div> element.

Anatomy

<primitives:field.root>
    <primitives:field.label />
    <primitives:field.control asChild="{true}">
        <!-- Your form input here -->
    </primitives:field.control>
    <primitives:field.description />
    <primitives:field.error />
</primitives:field.root>