Field Array

A repeatable group of fields, for letting users add and remove rows like "add another person".

First name

Last name

First name

Last name

<f:variable name="people" value="{0: {firstName: 'Ada', lastName: 'Lovelace'}, 1: {firstName: 'Alan', lastName: 'Turing'}}" />

<ui:fieldArray.root name="people" itemCount="{people -> f:count()}" class="w-full max-w-md">
    <primitives:fieldArray.itemTemplate>
        <ui:fieldArray.item>
            <div class="grid grid-cols-2 gap-3">
                <ui:field.root name="firstName" required="{true}">
                    <ui:input.root>
                        <ui:input.label>First name</ui:input.label>
                        <ui:input.input />
                    </ui:input.root>
                    <ui:field.errorText />
                </ui:field.root>
                <ui:field.root name="lastName" required="{true}">
                    <ui:input.root>
                        <ui:input.label>Last name</ui:input.label>
                        <ui:input.input />
                    </ui:input.root>
                    <ui:field.errorText />
                </ui:field.root>
            </div>
            <ui:fieldArray.removeTrigger asChild="{true}">
                <ui:button variant="ghost">Remove</ui:button>
            </ui:fieldArray.removeTrigger>
        </ui:fieldArray.item>
    </primitives:fieldArray.itemTemplate>

    <ui:fieldArray.itemGroup>
        <f:for each="{people}" as="person" iteration="it">
            <ui:fieldArray.item index="{it.index}">
                <div class="grid grid-cols-2 gap-3">
                    <ui:field.root name="firstName" defaultValue="{person.firstName}" required="{true}">
                        <ui:input.root>
                            <ui:input.label>First name</ui:input.label>
                            <ui:input.input />
                        </ui:input.root>
                        <ui:field.errorText />
                    </ui:field.root>
                    <ui:field.root name="lastName" defaultValue="{person.lastName}" required="{true}">
                        <ui:input.root>
                            <ui:input.label>Last name</ui:input.label>
                            <ui:input.input />
                        </ui:input.root>
                        <ui:field.errorText />
                    </ui:field.root>
                </div>
                <ui:fieldArray.removeTrigger asChild="{true}">
                    <ui:button variant="ghost">Remove</ui:button>
                </ui:fieldArray.removeTrigger>
            </ui:fieldArray.item>
        </f:for>
        <ui:fieldArray.emptyState>No people added yet.</ui:fieldArray.emptyState>
    </ui:fieldArray.itemGroup>

    <ui:fieldArray.addTrigger asChild="{true}">
        <ui:button variant="secondary">Add person</ui:button>
    </ui:fieldArray.addTrigger>
</ui:fieldArray.root>

Features

Add and remove rows client-side, with contiguous name[0], name[1], ... indexing maintained automatically as rows are removed
Existing rows render for real on the server - no JavaScript required to see or submit data that's already there
Works with Field and any Field-aware primitive (Input, Select, Checkbox, ...) nested inside a row
Row names use the same bracket notation (people[0][firstName]) Extbase and FormValues already understand
Optional minItems/maxItems bounds - addTrigger/removeTrigger disable themselves once a bound is reached, and append()/remove() are no-ops past it
emptyState/addTrigger/removeTrigger already reflect the correct hidden/disabled state in the server-rendered HTML, from itemCount, not only once JavaScript hydrates

Anatomy

<primitives:fieldArray.root itemCount="{items -> f:count()}">
    <primitives:fieldArray.itemTemplate>
        <primitives:fieldArray.item>
            <!-- Your row's fields here -->
            <primitives:fieldArray.removeTrigger />
        </primitives:fieldArray.item>
    </primitives:fieldArray.itemTemplate>
    <primitives:fieldArray.itemGroup>
        <f:for each="{items}" as="item">
            <primitives:fieldArray.item index="{...}">
                <!-- Your row's fields here -->
                <primitives:fieldArray.removeTrigger />
            </primitives:fieldArray.item>
        </f:for>
        <primitives:fieldArray.emptyState />
    </primitives:fieldArray.itemGroup>
    <primitives:fieldArray.addTrigger />
</primitives:fieldArray.root>

Installation

typo3 ui:add field-array

Read more about installing Components and Primitives.

Also install Field

FieldArray only manages rows and indexing - each row's own fields still need the Field primitive (typo3 ui:add field) nested inside.

How It Works

A row's markup is authored once, inside itemTemplate - a <template> element that's never rendered directly, only cloned client-side whenever addTrigger is clicked. Existing rows are a separate, ordinary loop over data you already have, rendered for real:

<primitives:fieldArray.itemTemplate>
    <primitives:fieldArray.item>
        <!-- one row's fields, authored once -->
    </primitives:fieldArray.item>
</primitives:fieldArray.itemTemplate>

<primitives:fieldArray.itemGroup>
    <f:for each="{people}" as="person" iteration="it">
        <primitives:fieldArray.item index="{it.index}">
            <!-- the same row markup, authored again with this person's data -->
        </primitives:fieldArray.item>
    </f:for>
</primitives:fieldArray.itemGroup>

Yes, the row is written twice - once for the stencil, once for the loop. This isn't a shortcut taken for FieldArray specifically; it's the same pattern FileUpload already uses for mixing already-uploaded files with newly-picked ones (see its docs' "Editing" section), and it's what keeps every row genuinely server-rendered rather than reconstructed from JSON after the page loads.

Each fieldArray.item's index prop (omitted inside itemTemplate, where no real index exists yet) automatically prefixes every nested Field's name - <ui:field name="firstName"> inside row 1 of an array named people becomes people[1][firstName] without you writing that out yourself.

Rows and the Trusted Properties of an Extbase Form

Inside a Form bound to a persisted object, the form signs the field names of every row rendered on the server into __trustedProperties (people[0][firstName], people[1][firstName], ...). The stencil in itemTemplate is left out, because its index is only known once the client adds the row. Extbase rejects a name that is not signed for a persisted object, so allow the properties of the rows added on the client in the property mapping configuration of the argument, e.g. forProperty('people.*')->allowAllProperties() in the initialize...Action.

Reflecting Row Count on the Server

root takes a required itemCount prop - the number of rows you're about to render in the loop above. Nothing counts your rows for you (they're your own f:for loop, not a collection FieldArray owns), so pass it explicitly, e.g. itemCount="{people -> f:count()}". It's what lets emptyState/addTrigger/removeTrigger start in the correct hidden/disabled state in the server-rendered HTML itself, matching minItems/maxItems, rather than only correcting themselves once JavaScript hydrates.

<primitives:fieldArray.root name="people" itemCount="{people -> f:count()}">
    <!-- ... -->
</primitives:fieldArray.root>

Examples

Starting Empty

A FieldArray with no rows yet - emptyState shows until the first row is added.

No people added yet.

<ui:fieldArray.root name="people" itemCount="0" class="w-full max-w-md">
    <primitives:fieldArray.itemTemplate>
        <ui:fieldArray.item>
            <div class="grid grid-cols-2 gap-3">
                <ui:field.root name="firstName" required="{true}">
                    <ui:input.root>
                        <ui:input.label>First name</ui:input.label>
                        <ui:input.input />
                    </ui:input.root>
                    <ui:field.errorText />
                </ui:field.root>
                <ui:field.root name="lastName" required="{true}">
                    <ui:input.root>
                        <ui:input.label>Last name</ui:input.label>
                        <ui:input.input />
                    </ui:input.root>
                    <ui:field.errorText />
                </ui:field.root>
            </div>
            <ui:fieldArray.removeTrigger asChild="{true}">
                <ui:button variant="ghost">Remove</ui:button>
            </ui:fieldArray.removeTrigger>
        </ui:fieldArray.item>
    </primitives:fieldArray.itemTemplate>

    <ui:fieldArray.itemGroup>
        <ui:fieldArray.emptyState>No people added yet.</ui:fieldArray.emptyState>
    </ui:fieldArray.itemGroup>

    <ui:fieldArray.addTrigger asChild="{true}">
        <ui:button variant="secondary">Add person</ui:button>
    </ui:fieldArray.addTrigger>
</ui:fieldArray.root>

Limiting Row Count

minItems="1" disables removeTrigger once a single row remains; maxItems="3" disables addTrigger once three rows exist. The status text below the rows ("2 of 3 added") isn't a FieldArray feature by itself - it's a plain element the row markup authors itself ({ui:ref(name: 'status', context: 'fieldArray')}), kept in sync from onItemAdded/onItemRemoved the same way this example already mounts each row's own Field/Input.

First name

Last name

1 of 3 added (2 remaining)

<f:variable name="people" value="{0: {firstName: 'Ada', lastName: 'Lovelace'}}" />
<f:variable name="peopleCount" value="{people -> f:count()}" />
<f:variable name="maxPeople" value="3" />

<ui:fieldArray.root name="people" itemCount="{peopleCount}" minItems="1" maxItems="{maxPeople}" class="w-full max-w-md">
    <primitives:fieldArray.itemTemplate>
        <ui:fieldArray.item>
            <div class="grid grid-cols-2 gap-3">
                <ui:field.root name="firstName" required="{true}">
                    <ui:input.root>
                        <ui:input.label>First name</ui:input.label>
                        <ui:input.input />
                    </ui:input.root>
                    <ui:field.errorText />
                </ui:field.root>
                <ui:field.root name="lastName" required="{true}">
                    <ui:input.root>
                        <ui:input.label>Last name</ui:input.label>
                        <ui:input.input />
                    </ui:input.root>
                    <ui:field.errorText />
                </ui:field.root>
            </div>
            <ui:fieldArray.removeTrigger asChild="{true}">
                <ui:button variant="ghost">Remove</ui:button>
            </ui:fieldArray.removeTrigger>
        </ui:fieldArray.item>
    </primitives:fieldArray.itemTemplate>

    <ui:fieldArray.itemGroup>
        <f:for each="{people}" as="person" iteration="it">
            <ui:fieldArray.item index="{it.index}">
                <div class="grid grid-cols-2 gap-3">
                    <ui:field.root name="firstName" defaultValue="{person.firstName}" required="{true}">
                        <ui:input.root>
                            <ui:input.label>First name</ui:input.label>
                            <ui:input.input />
                        </ui:input.root>
                        <ui:field.errorText />
                    </ui:field.root>
                    <ui:field.root name="lastName" defaultValue="{person.lastName}" required="{true}">
                        <ui:input.root>
                            <ui:input.label>Last name</ui:input.label>
                            <ui:input.input />
                        </ui:input.root>
                        <ui:field.errorText />
                    </ui:field.root>
                </div>
                <ui:fieldArray.removeTrigger asChild="{true}">
                    <ui:button variant="ghost">Remove</ui:button>
                </ui:fieldArray.removeTrigger>
            </ui:fieldArray.item>
        </f:for>
        <ui:fieldArray.emptyState>No people added yet.</ui:fieldArray.emptyState>
    </ui:fieldArray.itemGroup>

    <div {ui:ref(name: 'status', context: 'fieldArray')} class="text-sm text-muted-foreground">{peopleCount} of {maxPeople} added ({maxPeople - peopleCount} remaining)</div>

    <ui:fieldArray.addTrigger asChild="{true}">
        <ui:button variant="secondary">Add person</ui:button>
    </ui:fieldArray.addTrigger>
</ui:fieldArray.root>

Rows With Portalled Components

A row that composes components rendering their content through ui:portal: a Select, a DatePicker and a Popover. A portal inside itemTemplate renders in place, wrapped in <div data-portal>, because the stencil is inert. When a row is added, the clone moves the wrapper to where the portal wants to go - the end of <body>, or after the ui:portalContainer of its name - and removing the row removes it again. A ui:portal with disabled stays in the row. The row's entry file mounts the components the clone brought along with mountAll. The row is written once, in an <f:section name="row"> that the stencil and the loop both f:render - a long row does not have to be maintained twice.

First name

Favorite fruit

Date of birth

<ui:listCollection
    items="{
        0: {value: 'apple', label: 'Apple'},
        1: {value: 'banana', label: 'Banana'},
        2: {value: 'cherry', label: 'Cherry'}
    }"
    as="fruits" />
<f:variable name="people" value="{0: {firstName: 'Ada', favoriteFruit: 'cherry'}}" />

<ui:fieldArray.root
    name="people"
    itemCount="{people -> f:count()}"
    autoMount="{false}"
    rootId="complex-people"
    class="w-full max-w-md">
    <primitives:fieldArray.itemTemplate>
        <ui:fieldArray.item class="grid gap-3 rounded-md border p-3">
            <f:render section="row" arguments="{person: {}, fruits: fruits}" />
        </ui:fieldArray.item>
    </primitives:fieldArray.itemTemplate>

    <ui:fieldArray.itemGroup class="grid gap-3">
        <f:for each="{people}" as="person" iteration="it">
            <ui:fieldArray.item index="{it.index}" class="grid gap-3 rounded-md border p-3">
                <f:render section="row" arguments="{person: person, fruits: fruits}" />
            </ui:fieldArray.item>
        </f:for>
        <ui:fieldArray.emptyState>No people added yet.</ui:fieldArray.emptyState>
    </ui:fieldArray.itemGroup>

    <ui:fieldArray.addTrigger asChild="{true}">
        <ui:button variant="secondary">Add person</ui:button>
    </ui:fieldArray.addTrigger>
</ui:fieldArray.root>

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

<f:section name="row">
    <div class="grid grid-cols-2 gap-3">
        <ui:field.root name="firstName" defaultValue="{person.firstName}" required="{true}">
            <ui:input.root>
                <ui:input.label>First name</ui:input.label>
                <ui:input.input />
            </ui:input.root>
            <ui:field.errorText />
        </ui:field.root>
        <ui:field.root name="favoriteFruit" defaultValue="{person.favoriteFruit}">
            <ui:select.root collection="{fruits}">
                <ui:select.label>Favorite fruit</ui:select.label>
                <ui:select.control>
                    <ui:select.trigger placeholder="Choose a fruit" />
                </ui:select.control>
                <ui:select.content>
                    <ui:select.list>
                        <f:for each="{fruits.items}" as="fruit">
                            <ui:select.item item="{fruit}">
                                <ui:select.itemText>{fruit.label}</ui:select.itemText>
                                <ui:select.itemIndicator />
                            </ui:select.item>
                        </f:for>
                    </ui:select.list>
                </ui:select.content>
            </ui:select.root>
        </ui:field.root>
    </div>
    <ui:field.root name="birthDate">
        <ui:datePicker.root>
            <ui:datePicker.label>Date of birth</ui:datePicker.label>
            <ui:datePicker.control>
                <ui:datePicker.input />
                <ui:datePicker.trigger />
            </ui:datePicker.control>
            <ui:datePicker.content>
                <f:for each="{0: 'day', 1: 'month', 2: 'year'}" as="view">
                    <ui:datePicker.view view="{view}">
                        <ui:datePicker.viewControl view="{view}">
                            <ui:datePicker.prevTrigger view="{view}" />
                            <ui:datePicker.viewTrigger view="{view}">
                                <ui:datePicker.rangeText />
                            </ui:datePicker.viewTrigger>
                            <ui:datePicker.nextTrigger view="{view}" />
                        </ui:datePicker.viewControl>
                        <ui:datePicker.table view="{view}">
                            <ui:datePicker.tableHeader />
                            <ui:datePicker.tableBody />
                        </ui:datePicker.table>
                    </ui:datePicker.view>
                </f:for>
            </ui:datePicker.content>
        </ui:datePicker.root>
    </ui:field.root>
    <div class="flex items-center justify-between">
        <ui:popover.root>
            <ui:popover.trigger asChild="{true}">
                <ui:button variant="outline" type="button">Tips</ui:button>
            </ui:popover.trigger>
            <ui:popover.content>
                <ui:popover.title>About this row</ui:popover.title>
                <ui:popover.description>The popover, the select and the date picker of this row all render their content into the end of the body.</ui:popover.description>
            </ui:popover.content>
        </ui:popover.root>
        <ui:fieldArray.removeTrigger asChild="{true}">
            <ui:button variant="ghost">Remove</ui:button>
        </ui:fieldArray.removeTrigger>
    </div>
</f:section>

import { mount, mountAll } from 'fluid-primitives';
import { DatePicker } from 'fluid-primitives/date-picker';
import { Field } from 'fluid-primitives/field';
import { FieldArray } from 'fluid-primitives/field-array';
import { Input } from 'fluid-primitives/input';
import { Popover } from 'fluid-primitives/popover';
import { Select } from 'fluid-primitives/select';

// A row added on the client contains components that are not hydrated yet. `mountAll` skips the
// ones that are, so running it for everything a row composes is safe on every added row. The
// popover, the select and the date picker of the row render their content through `ui:portal`:
// the clone moves it to the end of the body before these mount.
function mountRowComponents() {
    mountAll('ui:field', ({ props }) => {
        const field = new Field(props);
        field.init();
        return field;
    });
    mountAll('ui:input', ({ props }) => {
        const input = new Input(props);
        input.init();
        return input;
    });
    mountAll('ui:select', ({ props }) => {
        const select = new Select(props);
        select.init();
        return select;
    });
    mountAll('ui:datePicker', ({ props }) => {
        const datePicker = new DatePicker(props);
        datePicker.init();
        return datePicker;
    });
    mountAll('ui:popover', ({ props }) => {
        const popover = new Popover(props);
        popover.init();
        return popover;
    });
}

mount('ui:fieldArray', 'complex-people', ({ props }) => {
    const fieldArray = new FieldArray({ ...props, onItemAdded: mountRowComponents });
    fieldArray.init();
    return fieldArray;
});

Full Form With Client-Side Validation

A complete Form wrapping a FieldArray of guests, each with a name/email pair - required fields and the email format are validated live as you type or blur, using a Zod schema passed straight to validation. z.array(z.object({...})) covers however many guest rows currently exist (added or removed) without FieldArray needing to know about validation at all - each issue's own path (e.g. ['guests', 0, 'email']) is matched back to the exact row's own field automatically. Submission is blocked until every row is valid.

<ui:exposeToClient />

<ui:form.root actionUri="#" autoMount="{false}" rootId="{rootId}-form" class="w-full max-w-md">
    <ui:form.content class="space-y-6">
        <ui:fieldArray.root name="guests" itemCount="1">
            <primitives:fieldArray.itemTemplate>
                <ui:fieldArray.item>
                    <div class="grid grid-cols-2 gap-3">
                        <ui:field.root name="name" required="{true}">
                            <ui:input.root>
                                <ui:input.label>Name</ui:input.label>
                                <ui:input.input />
                            </ui:input.root>
                            <ui:field.errorText />
                        </ui:field.root>
                        <ui:field.root name="email" required="{true}">
                            <ui:input.root type="email">
                                <ui:input.label>Email</ui:input.label>
                                <ui:input.input />
                            </ui:input.root>
                            <ui:field.errorText />
                        </ui:field.root>
                    </div>
                    <ui:fieldArray.removeTrigger asChild="{true}">
                        <ui:button variant="ghost">Remove</ui:button>
                    </ui:fieldArray.removeTrigger>
                </ui:fieldArray.item>
            </primitives:fieldArray.itemTemplate>

            <ui:fieldArray.itemGroup>
                <ui:fieldArray.item index="0">
                    <div class="grid grid-cols-2 gap-3">
                        <ui:field.root name="name" required="{true}">
                            <ui:input.root>
                                <ui:input.label>Name</ui:input.label>
                                <ui:input.input />
                            </ui:input.root>
                            <ui:field.errorText />
                        </ui:field.root>
                        <ui:field.root name="email" required="{true}">
                            <ui:input.root type="email">
                                <ui:input.label>Email</ui:input.label>
                                <ui:input.input />
                            </ui:input.root>
                            <ui:field.errorText />
                        </ui:field.root>
                    </div>
                    <ui:fieldArray.removeTrigger asChild="{true}">
                        <ui:button variant="ghost">Remove</ui:button>
                    </ui:fieldArray.removeTrigger>
                </ui:fieldArray.item>
            </ui:fieldArray.itemGroup>

            <ui:fieldArray.addTrigger asChild="{true}">
                <ui:button variant="secondary">Add guest</ui:button>
            </ui:fieldArray.addTrigger>
        </ui:fieldArray.root>

        <ui:button type="submit">Send invitations</ui:button>
    </ui:form.content>

    <ui:form.indicator
        state="{f:constant(name: 'Jramke\FluidPrimitives\Enum\FormState::Success')}"
        class="space-y-3">
        <ui:form.successText class="block">Invitations sent!</ui:form.successText>
        <ui:button type="reset">Reset</ui:button>
    </ui:form.indicator>
</ui:form.root>

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

import { getHydrationData, mountAll } from 'fluid-primitives';
import { Form } from 'fluid-primitives/form';
import { z } from 'zod';

// Every guest row's own name/email fields are already validated live by the Field/Input
// primitives nested inside FieldArray - Zod just describes what "valid" means per row. Its own
// issue path (e.g. ['guests', 0, 'name']) is matched back to the exact field name Field itself
// renders (`guests[0][name]`) automatically, however many rows currently exist (added or removed
// client-side) - no fixed field list needed.
const guestListSchema = z.object({
    guests: z.array(
        z.object({
            name: z.string().min(1, 'Name is required.'),
            email: z.email('A valid email address is required.'),
        })
    ),
});

mountAll('ui:guestList', ({ props }) => {
    const data = getHydrationData('ui:form', props.id + '-form');
    if (!data) return;

    const form = new Form({
        ...data.props,
        validation: guestListSchema,
        onSubmit: async ({ values }) => {
            alert(JSON.stringify(values.toObject()));
            return true;
        },
    });

    form.init();
});

API Reference

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

fieldArray.root

Contains every part of the field array. Renders a <div> element.

Name	Description	Required	Default
`name`	`string` The base field name for this array's rows, e.g. `people` - each row's nested fields are automatically prefixed with it and their row index, producing names like `people[0][firstName]`.	Yes	-
`itemCount`	`integer` Number of rows rendered server-side, e.g. `itemCount=""`. Lets `emptyState`/`addTrigger`/`removeTrigger` reflect the correct hidden/disabled state before JavaScript hydrates, instead of only afterward.	Yes	-
`minItems`	`integer` Minimum number of rows required - once exactly this many remain, removing a row is disabled.	No	-
`maxItems`	`integer` Maximum number of rows allowed - once this many exist, adding a row is disabled.	No	-
`translations`	`array` Localized screen-reader announcements for adding/removing a row. A `%number%` placeholder is replaced with the row's 1-based position. Set an entry to `` to disable that announcement, or (client-side only, via the FieldArray constructor) pass a callback to build the message from the row's own field values instead. Use `f:translate` for per-template localization overrides when needed.	No	-
`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	-

fieldArray.itemTemplate

Wraps one row's markup, authored once and cloned client-side for each added row. Renders a <template> element - never visible itself.

fieldArray.itemGroup

Groups every row, existing and added. 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	-

fieldArray.item

One row. Existing rows are authored directly with an index; added rows are cloned from itemTemplate, which omits it. Renders a <div> element.

Name	Description	Required	Default
`index`	`integer` This row's position in the array, e.g. `0`. Required for a real row; omitted inside `itemTemplate`'s stencil, where the client fills in a real index on each clone.	No	-
`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	-

fieldArray.emptyState

Shown while itemGroup has no rows yet. 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	-

fieldArray.addTrigger

Appends a new row, cloned from itemTemplate. Renders a <button> 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	-

Rendered data attributes

Attribute	Description
`data-disabled`	Present when disabled

fieldArray.removeTrigger

Removes its enclosing row and re-indexes every later row down by one. Renders a <button> 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	-

Rendered data attributes

Attribute	Description
`data-disabled`	Present when disabled
`data-value`	The index of the row the trigger removes.

Machine options

Name	Description	Default
`id`	`string` The unique identifier of the field array.	-
`name`	`string` The name the rows are nested under, e.g. `people` for `people[0][firstName]`.	-
`itemCount`	`number \| undefined` The number of rows the server rendered. It sets the state of the triggers before hydration, once the client runs it counts the rows in the DOM instead.	-
`minItems`	`number \| undefined` The fewest rows allowed. At this many, `remove()` and the remove triggers do nothing and the remove triggers are disabled.
`maxItems`	`number \| undefined` The most rows allowed. At this many, `append()` and the add trigger do nothing and the add trigger is disabled.	-
`translations`	`{ rowAdded?: FieldArrayAnnounceTranslation; rowRemoved?: FieldArrayAnnounceTranslation; } \| undefined` The screen reader announcements of an added and a removed row. In a string, `%number%` is replaced with the 1-based position of the row, e.g. `Row %number% removed.`. A callback builds the message from the data of the row, and may use `%number%` in what it returns.	-
`onItemAdded`	`((detail: { index: number; componentNames: string[] }) => void) \| undefined` Called after a row was added by the add trigger, with its index and the client names of the components inside it, e.g. `['field', 'input']`. Call their `mountAll()` here: the field array doesn't know what the template of a row contains.	-
`onItemRemoved`	`((detail: { index: number }) => void) \| undefined` Called after a row was removed by its remove trigger, with the index it had. The later rows have already moved up by then.	-

Machine JavaScript API

Name	Type	Description
`getRows`	`() => { index: number }[]`	The rows that currently exist, by index.
`canAppend`	`() => boolean`	Whether `append()` would currently add a row, i.e. `maxItems` hasn't been reached.
`canRemove`	`() => boolean`	Whether `remove()` would currently remove a row, i.e. more than `minItems` remain.
`append`	`() => void`	Adds a row, if `maxItems` allows it.
`remove`	`(index: number) => void`	Removes the row at `index`, if `minItems` allows it.

Field Array

Features

Anatomy

Installation

How It Works

Rows and the Trusted Properties of an Extbase Form

Reflecting Row Count on the Server

Examples

Starting Empty

Limiting Row Count

Rows With Portalled Components

Full Form With Client-Side Validation

API Reference

fieldArray.root

fieldArray.itemTemplate

fieldArray.itemGroup

fieldArray.item

fieldArray.emptyState

fieldArray.addTrigger

Rendered data attributes

fieldArray.removeTrigger

Rendered data attributes

Machine options

Machine JavaScript API

On this page