Form

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

<ui:exposeToClient />

<ui:form controlled="{true}" rootId="example-form" class="min-w-[275px]">

    <ui:field.root name="homepage" required="{true}" defaultValue="https://example.com">
        <ui:field.label>Homepage</ui:field.label>
        <ui:field.control asChild="{true}">
            <ui:input type="url" placeholder="https://example.com" />
        </ui:field.control>
        <ui:field.error />
    </ui:field.root>

    <ui:button type="submit">Submit</ui:button>
</ui:form>

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

import { getHydrationData, mount } from 'fluid-primitives';
import { Form, ValidationError } from 'fluid-primitives/form';

mount('form-example', () => {
	const data = getHydrationData('form', 'example-form');
	if (!data) return;

	const form = new Form({
		...data.props,
		onSubmit: async ({ formData, api }) => {
			await new Promise(resolve => setTimeout(resolve, 800));

			const formEl = api.getFormEl();
			const urlInput = formEl?.querySelector<HTMLInputElement>('input[name="homepage"]');
			if (!urlInput?.checkValidity()) {
				throw new ValidationError({
					homepage: { messages: ['Please enter a valid url.'] },
				});
			}

			if (formData.get('homepage') === 'https://example.com') {
				throw new ValidationError({
					homepage: { messages: ['The example homepage is not allowed.'] },
				});
			}

			console.log(Object.fromEntries(formData.entries()));

			return true;
		},
		render: form => {
			form.api
				.getFormEl()
				?.querySelector('button[type="submit"]')
				?.setAttribute('aria-disabled', form.api.isSubmitting ? 'true' : 'false');
		},
	});

	form.init();
});

Features

Optional client-side validation with Zod schema support
AJAX form submission with automatic error handling
Seamless Extbase controller integration
Real-time field validation on blur and input
Form state management (submitting, dirty, invalid, success, error)
Works with all Field-aware components and basic HTML inputs
Automatic field name prefixing for Extbase

Installation

typo3 ui:add form

Read more about installing Components and Primitives.

API Reference

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

form

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'

Anatomy

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