Form

A powerful form component with client-side validation, AJAX submission, and seamless Extbase integration.

<ui:exposeToClient />

<ui:form.root action="homepage" autoMount="{false}" rootId="example-form" class="min-w-[275px]">

    <ui:form.content class="space-y-4">
        <ui:field.root name="homepage" required="{true}">
            <ui:field.label>Homepage</ui:field.label>
            <ui:input.root type="url">
                <ui:input.input pattern="https?://.*" placeholder="https://example.com" />
            </ui:input.root>
            <ui:field.helperText>Use `https://down.example.com` to preview the generic error state.</ui:field.helperText>
            <ui:field.errorText />
        </ui:field.root>

        <f:variable name="submitLabelId" value="{ui:id()}" />
        <ui:button
            type="submit"
            focusableWhenDisabled="{true}"
            aria-labelledby="{submitLabelId}"
            autoMount="{false}"
            rootId="example-form-submit">
            <span id="{submitLabelId}">
                <ui:button.indicator state="{f:constant(name: 'Jramke\FluidPrimitives\Enum\ButtonIndicatorState::Idle')}">Submit</ui:button.indicator>
                <ui:button.indicator state="{f:constant(name: 'Jramke\FluidPrimitives\Enum\ButtonIndicatorState::Loading')}">Submitting...</ui:button.indicator>
            </span>
        </ui:button>
    </ui:form.content>

    <ui:form.indicator
        state="{f:constant(name: 'Jramke\FluidPrimitives\Enum\FormState::Error')}"
        class="space-y-3">
        <p class="font-medium">Submission failed</p>
        <ui:form.errorText class="block">The demo server is unavailable right now.</ui:form.errorText>
        <ui:button type="reset">Try again</ui:button>
    </ui:form.indicator>

    <ui:form.indicator
        state="{f:constant(name: 'Jramke\FluidPrimitives\Enum\FormState::Success')}"
        class="space-y-3">
        <p class="font-medium">Submitted</p>
        <ui:form.successText class="block">Your homepage was submitted successfully.</ui:form.successText>
        <ui:button type="reset">Submit another</ui:button>
    </ui:form.indicator>
</ui:form.root>

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

import { getHydrationData, mount, mountAll } from 'fluid-primitives';
import { Button } from 'fluid-primitives/button';
import { Form } from 'fluid-primitives/form';

mountAll('ui:formExample', () => {
    const data = getHydrationData('ui:form', 'example-form');
    if (!data) return;

    const submitButton = mount('ui:button', 'example-form-submit', ({ props }) => {
        const button = new Button(props);
        button.init();
        return button;
    });

    const form = new Form({
        ...data.props,
        validation: ({ values }) => {
            const homepage = values.get('homepage');
            if (typeof homepage !== 'string' || homepage.trim() === '') {
                return {
                    homepage: { messages: ['Please enter an url.'] },
                };
            }

            try {
                new URL(homepage);
            } catch {
                return {
                    homepage: { messages: ['Please enter a valid url.'] },
                };
            }

            if (homepage === 'https://example.com') {
                return {
                    homepage: { messages: ['The example homepage is not allowed.'] },
                };
            }
        },
        onSubmit: async ({ api, post }) => {
            const [response] = await Promise.all([
                post(api.getAction()),
                new Promise(resolve => setTimeout(resolve, 800)),
            ]);

            const data = await response.json();

            if (!response.ok) {
                api.setErrorText(data.message || 'The demo server is unavailable right now.');
                return false;
            }

            api.setSuccessText(data.message || 'Your homepage was submitted successfully.');

            return true;
        },
        render: form => submitButton?.api.setLoading(form.api.isSubmitting),
    });

    form.init();
});

Features

Optional client-side validation with Standard Schema-compatible validators or custom callbacks
AJAX form submission with automatic error handling
Seamless Extbase controller integration
Field validation that follows the validation mode, from native constraints, your schema or callback, and async checks of single fields
Form state management (submitting, dirty, invalid, success, error)
Built-in primitives for editable content, state indicators, and status text
Works with all Field-aware components and basic HTML inputs
Automatic field name prefixing for Extbase

See the complete Form Guide for a complete form integration.

Anatomy

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

    <primitives:form.indicator
        state="{f:constant(name: 'Jramke\FluidPrimitives\Enum\FormState::Error')}"
    >
        <primitives:form.errorText />
    </primitives:form.indicator>
</primitives:form.root>

Installation

typo3 ui:add form

Read more about installing Components and Primitives.

Client-side validation is configured in your entry file with the validation option, not in the Fluid template. Pass either a Standard Schema-compatible validator such as Zod or a synchronous callback that reads the values object. values uses your field names as dot paths such as person.name, keeps leaf values as string | File, exposes arrays through getAll(), and can be converted to a nested object with toObject() or partially read with pick(). Validation and server errors stay flat and field-keyed, so nested fields still return errors under keys such as person.name. For submit results, return true, false, or field errors from onSubmit, and use api.setErrorText() or api.setSuccessText() for form-level messages. Use post(url) to submit the current form as FormData. Fields read their value inputDebounceMs after the last change (100 by default, never less than 50), so typing does not validate on every keystroke.

API Reference

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

form.root

Submits and manages the form state. Renders a <form> element.

Name	Description	Required	Default
`actionUri`	`string` The resolved form action URI to submit to directly.	No	-
`action`	`string` The Extbase action name used to build the form action URI.	No	-
`extensionName`	`string` The Extbase extension name used to build the form action URI.	No	-
`pluginName`	`string` The Extbase plugin name used to build the form action URI.	No	-
`controller`	`string` The Extbase controller name used to build the form action URI.	No	-
`arguments`	`array` The Extbase arguments used to build the form action URI.	No	-
`pageUid`	`int` The target page UID used to build the form action URI.	No	-
`objectName`	`string` The object name prefix used for nested form field names.	No	-
`object`	`mixed` The bound object used for form value mapping.	No	-
`method`	`string` The HTTP method used for form submission.	No	'post'
`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-state`	The state of the form. One of: "invalid", "ready", "submitting", "success", "error".
`data-submitting`	Present while the form is being submitted.
`data-invalid`	Present when invalid
`data-dirty`	Present when dirty
`data-touched`	Present when touched

form.content

Wraps the editable form UI. It stays visible in ready, invalid, and submitting, and hides in error and success. Renders a <div> 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	-

form.indicator

Displays content for an exact form state such as error, success, or submitting. Renders a <div> element.

Name	Description	Required	Default
`state`	`Enum\FormState` The form state to render.	Yes	-
`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	-

form.errorText

Displays the current form-level error text set through the Form API, or its slotted fallback text. 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	-

form.successText

Displays the current form-level success text set through the Form API, or its slotted fallback text. 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 form.	-
`validation`	`FormValidation \| undefined` Validates the values of the form on the client: a Standard Schema validator such as Zod, or a synchronous callback that gets the `values` and returns the errors by field name. It cannot be set from a Fluid template, only by constructing `Form` in your own entry file.	-
`objectName`	`string \| undefined` The object name that prefixes the names of nested form fields.	-
`inputDebounceMs`	`number \| undefined` How long the fields wait after the last change before they read their value, never less than 50. A `validate` that sends a request should not fire on every keystroke.	100
`onSubmit`	`(({ values, api, event, post }: { values: FormValues; api: FormApi; event: JSX.FormEvent<HTMLElement>; post: (url: string) => Promise<Response>; }) => Promise<FormSubmitResult> \| FormSubmitResult) \| undefined` Called with the values once the form is valid and submitted. Return `true` for success, `false` for an error, or field errors to mark the form invalid. `post(url)` submits the form as `FormData` and maps a 422 JSON response to field errors for you.	-
`render`	`((form: Form) => void) \| undefined` Called every time the form state changes. Use it to update UI the form does not wire itself.	-

Machine JavaScript API

Name	Type	Description
`isSubmitting`	`boolean`	Whether the form is being submitted.
`isDirty`	`boolean`	Whether the value of any field differs from the one it started with.
`isInvalid`	`boolean`	Whether any field is invalid.
`isSuccessful`	`boolean`	Whether the last submit succeeded.
`isError`	`boolean`	Whether the last submit ended in an error.
`getValues`	`() => FormValues`	The current values of the form.
`getErrors`	`() => FormErrors`	The errors of the invalid fields, by field name.
`getDirty`	`() => FormDirty`	The dirty fields, by field name.
`getTouched`	`() => FormTouched`	The touched fields, by field name.
`getErrorText`	`() => string \| null`	The text of the error status of the form, `null` if there is none.
`setErrorText`	`(text: string \| null) => void`	Sets the text of the error status. Pass `null` to remove it.
`getSuccessText`	`() => string \| null`	The text of the success status of the form, `null` if there is none.
`setSuccessText`	`(text: string \| null) => void`	Sets the text of the success status. Pass `null` to remove it.
`clearStatusText`	`() => void`	Removes the error and the success text.
`getAllFields`	`() => Map<string, FieldHandle>`	Every field of the form, by name.
`getField`	`(name: string) => FieldHandle \| undefined`	The field with this name, `undefined` if the form has none.
`getFormEl`	`() => HTMLFormElement \| null`	The `<form>` element.
`getAction`	`() => string`	The `action` of the form, an empty string if it has none.
`reset`	`() => void`	Resets the form to its initial state.
`syncFields`	`() => void`	Picks up fields that were added or removed after the form was hydrated.
`renameField`	`(oldName: string, newName: string) => void`	Renames a field, keeping its value, touched, dirty and error state. Useful to keep the rows of a FieldArray contiguously indexed after one in the middle was removed.