# Field Array
**A repeatable group of fields, for letting users add and remove rows like "add another person".**
**Reference:** [View Source](https://github.com/jramke/fluid-primitives/tree/main/Resources/Private/Primitives/FieldArray)
**FieldArray.html**
```html
First nameLast name
Remove
First nameLast name
RemoveNo people added yet.Add person
```
**FieldArray.ts**
```ts
import { mountAll } from 'fluid-primitives';
import { Field } from 'fluid-primitives/field';
import { FieldArray, type FieldArrayAnnounceInfo } from 'fluid-primitives/field-array';
import { Input } from 'fluid-primitives/input';
// A row appended client-side (via api.append()) contains its own nested Field/Input instances
// that aren't hydrated yet - `mountAll` is safe to call more than once (already-mounted instances
// are skipped), so re-running these two on every `itemadded` picks up whatever a row's own
// itemTemplate contains without FieldArray needing to know about Field/Input itself.
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:fieldArray', ({ props }) => {
const serverTranslations = props.translations as
{ rowAdded?: string; rowRemoved?: string } | undefined;
const maxItems = props.maxItems as number | undefined;
const fieldArray = new FieldArray({
...props,
onItemAdded: () => {
mountRowComponents();
updateStatusText();
},
onItemRemoved: updateStatusText,
translations: {
...serverTranslations,
// A custom announcement built from the row's own fields, falling back to the
// translated default (with its `%number%` placeholder) while they're still empty -
// e.g. right after a row was just added and hasn't been filled in yet.
rowRemoved: ({ getFieldValue }: FieldArrayAnnounceInfo) => {
const firstName = getFieldValue('firstName');
const lastName = getFieldValue('lastName');
if (!firstName && !lastName) return serverTranslations?.rowRemoved ?? false;
return `Person ${[firstName, lastName].filter(Boolean).join(' ')} removed.`;
},
},
});
// Only the "Limiting Row Count" example authors a `status` ref inside its own row markup -
// `getElement` returns null for every other example, so this is a no-op there. Kept here
// rather than duplicated per-example since every example already shares this one entry file.
function updateStatusText() {
const statusEl = fieldArray.getElement('status');
if (!statusEl || maxItems === undefined) return;
const count = fieldArray.api.getRows().length;
statusEl.textContent = `${count} of ${maxItems} added (${maxItems - count} remaining)`;
}
fieldArray.init();
return fieldArray;
});
```
## 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 `name`s 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
## Installation
```bash
typo3 ui:add field-array
```
Or copy the files manually from GitHub (https://github.com/jramke/fluid-primitives.com/tree/main/packages/docs/Resources/Private/Registry/FieldArray) into your project.
Read more about installing [Components and Primitives](/docs/core-concepts/primitives.md).
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 `` 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:
```html
```
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` - `` inside row `1` of an array named `people` becomes `people[1][firstName]` without you writing that out yourself.
### 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.
```html
```
## Examples
### Starting Empty
A `FieldArray` with no rows yet - `emptyState` shows until the first row is added.
**FieldArray.html**
```html
First nameLast name
RemoveNo people added yet.Add person
```
### 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`.
**FieldArray.html**
```html
First nameLast name
Remove
First nameLast name
RemoveNo people added yet.
{peopleCount} of {maxPeople} added ({maxPeople - peopleCount} remaining)
Add person
```
### 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](/docs/core-concepts/forms.md#client-side-validation) 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.
**GuestList.html**
```html
NameEmail
Remove
NameEmail
RemoveAdd guestSend invitationsInvitations sent!Reset
```
**GuestList.entry.ts**
```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
### fieldArray.root
Contains every part of the field array. Renders a `
` element.
| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `name` | `string` | Yes | `-` | 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]`. |
| `itemCount` | `integer` | Yes | `-` | 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. |
| `minItems` | `integer` | No | `-` | Minimum number of rows required - once exactly this many remain, removing a row is disabled. |
| `maxItems` | `integer` | No | `-` | Maximum number of rows allowed - once this many exist, adding a row is disabled. |
| `translations` | `array` | No | `-` | 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. |
| `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. |
### fieldArray.itemTemplate
Wraps one row's markup, authored once and cloned client-side for each added row. Renders a `` element - never visible itself.
| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
### fieldArray.itemGroup
Groups every row, existing and added. Renders a `
` 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. |
### fieldArray.item
One row. Existing rows are authored directly with an `index`; added rows are cloned from `itemTemplate`, which omits it. Renders a `
` element.
| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `index` | `integer` | No | `-` | 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. |
| `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. |
### fieldArray.emptyState
Shown while `itemGroup` has no rows yet. Renders a `
` 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. |
### fieldArray.addTrigger
Appends a new row, cloned from `itemTemplate`. Renders a `