Open History to see the last commit
1---
2id: arrays
3title: Arrays
4---
5β
6TanStack Form fields can hold arrays just like any other value. The important distinction is whether the array is the field value itself or whether you're rendering fields for the items inside it.
7β
8If one control reads and replaces the whole array, use a regular field. If you're rendering fields for individual items and need to add, remove, or reorder them, use an array field.
9β
10This guide covers both cases and how to choose between them.
11β
12## An array as the field value
13β
14Use a regular field when one control reads and replaces the complete array. A
15multi-select, tag picker, or checkbox group can pass its next array to
16`handleChange` like any other field value:
17β
18<!-- ::start:framework -->
19β
20# React
21β
22```tsx
23<form.Field name="selectedRoleIds">
24 {(field) => (
25 <RolePicker
26 value={field.value}
27 onValueChange={(roleIds) => field.handleChange(roleIds)}
28 />
29 )}
30</form.Field>
31```
32β
33# Preact
34β
35```tsx
36<form.Field name="selectedRoleIds">
37 {(field) => (
38 <RolePicker
39 value={field.value}
40 onValueChange={(roleIds) => field.handleChange(roleIds)}
41 />
42 )}
43</form.Field>
44```
45β
46# Solid
47β
48```tsx
49<form.Field name="selectedRoleIds">
50 {(field) => (
51 <RolePicker
52 value={field().value}
53 onValueChange={(roleIds) => field().handleChange(roleIds)}
54 />
55 )}
56</form.Field>
57```
58β
59# Angular
60β
61```html
62<ng-container [tanstackField]="form" name="selectedRoleIds" #field="field">
63 <app-role-picker
64 [value]="field.api.value"
65 (valueChange)="field.api.handleChange($event)"
66 />
67</ng-container>
68```
69β
70# Lit
71β
72```ts
73this.form.field(
74 { name: 'selectedRoleIds' },
75 (field) => html`
76 <role-picker
77 .value=${field.value}
78 @value-change=${(event: CustomEvent<Array<string>>) =>
79 field.handleChange(event.detail)}
80 ></role-picker>
81 `,
82)
83```
84β
85# Svelte
86β
87```svelte
88<form.Field name="selectedRoleIds">
89 {#snippet children(field)}
90 <RolePicker
91 value={field.value}
92 onValueChange={(roleIds) => field.handleChange(roleIds)}
93 />
94 {/snippet}
95</form.Field>
96```
97β
98# Vue
99β
100```vue
101<form.Field name="selectedRoleIds" v-slot="{ field }">
102 <RolePicker
103 :model-value="field.value"
104 @update:model-value="field.handleChange"
105 />
106</form.Field>
107```
108β
109<!-- ::end:framework -->
110β
111## Rendering fields in an array
112β
113If you need to edit fields inside each array item, the previous approach has two problems.
114β
115- Editing any item's value would cause the whole array to rerender.
116- Moving items within the array would not update fields, since it was only changing the array's value.
117β
118<!-- ::start:framework -->
119β
120# React
121β
122This is where `form.ArrayField` comes in. It ensures that each item in the array is rendered independently, while still subscribing to
123item changes like swapping, removing or pushing new values.
124β
125```tsx
126<form.ArrayField name="people">
127 {(array) => (
128 <ul>
129 {array.value.map((person, index) => (
130 <li key={person.id}>
131 <form.Field name={`people[${index}].name`}>
132 {(field) => <TextInput field={field} />}
133 </form.Field>
134 </li>
135 ))}
136 </ul>
137 )}
138</form.ArrayField>
139```
140β
141# Preact
142β
143This is where `form.ArrayField` comes in. It ensures that each item in the array is rendered independently, while still subscribing to
144item changes like swapping, removing or pushing new values.
145β
146```tsx
147<form.ArrayField name="people">
148 {(array) => (
149 <ul>
150 {array.value.map((person, index) => (
151 <li key={person.id}>
152 <form.Field name={`people[${index}].name`}>
153 {(field) => <TextInput field={field} />}
154 </form.Field>
155 </li>
156 ))}
157 </ul>
158 )}
159</form.ArrayField>
160```
161β
162# Solid
163β
164This is where `form.ArrayField` comes in. It ensures that each item in the array is rendered independently, while still subscribing to
165item changes like swapping, removing or pushing new values.
166β
167```tsx
168<form.ArrayField name="people">
169 {(array) => (
170 <ul>
171 <For each={array().value}>
172 {(_person, index) => (
173 <li>
174 <form.Field name={`people[${index()}].name`}>
175 {(field) => <TextInput field={field} />}
176 </form.Field>
177 </li>
178 )}
179 </For>
180 </ul>
181 )}
182</form.ArrayField>
183```
184β
185# Angular
186β
187This is where `TanStackArrayField` comes in. It ensures that each item in the array is rendered independently, while still subscribing to
188item changes like swapping, removing or pushing new values.
189β
190```ts
191import { Component } from '@angular/core'
192import {
193 TanStackArrayField,
194 TanStackField,
195 injectForm,
196} from '@tanstack/angular-form'
197β
198@Component({
199 selector: 'app-people-form',
200 standalone: true,
201 imports: [TanStackArrayField, TanStackField],
202 template: `
203 <ng-container
204 [tanstackArrayField]="form"
205 name="people"
206 #people="arrayField"
207 >
208 <ul>
209 @for (person of people.api.value; track person.id; let index = $index) {
210 <li>
211 <ng-container
212 [tanstackField]="form"
213 [name]="personName(index)"
214 #field="field"
215 >
216 <app-text-input [field]="field.api" />
217 </ng-container>
218 </li>
219 }
220 </ul>
221 </ng-container>
222 `,
223})
224export class PeopleFormComponent {
225 form = injectForm({
226 defaultValues: {
227 people: [{ id: 'person-1', name: '' }],
228 },
229 })
230β
231 personName(index: number): `people[${number}].name` {
232 return `people[${index}].name`
233 }
234}
235```
236β
237# Lit
238β
239This is where `form.arrayField` comes in. It ensures that each item in the array is rendered independently, while still subscribing to
240item changes like swapping, removing or pushing new values.
241β
242```ts
243this.form.arrayField(
244 { name: 'people' },
245 (array) => html`
246 <ul>
247 ${repeat(
248 array.value,
249 (person) => person.id,
250 (_person, index) => html`
251 <li>
252 ${this.form.field(
253 { name: `people[${index}].name` },
254 (field) => html`<text-input .field=${field}></text-input>`,
255 )}
256 </li>
257 `,
258 )}
259 </ul>
260 `,
261)
262```
263β
264# Svelte
265β
266This is where `form.ArrayField` comes in. It ensures that each item in the array is rendered independently, while still subscribing to
267item changes like swapping, removing or pushing new values.
268β
269```svelte
270<form.ArrayField name="people">
271 {#snippet children(array)}
272 <ul>
273 {#each array.value as person, index (person.id)}
274 <li>
275 <form.Field name={`people[${index}].name`}>
276 {#snippet children(field)}
277 <TextInput field={field} />
278 {/snippet}
279 </form.Field>
280 </li>
281 {/each}
282 </ul>
283 {/snippet}
284</form.ArrayField>
285```
286β
287# Vue
288β
289This is where `form.ArrayField` comes in. It ensures that each item in the array is rendered independently, while still subscribing to
290item changes like swapping, removing or pushing new values.
291β
292```vue
293<form.ArrayField name="people" v-slot="{ field: array }">
294 <ul>
295 <li v-for="(person, index) in array.value" :key="person.id">
296 <form.Field :name="`people[${index}].name`" v-slot="{ field }">
297 <TextInput :field="field" />
298 </form.Field>
299 </li>
300 </ul>
301</form.ArrayField>
302```
303β
304<!-- ::end:framework -->
305β
306### Keeping item identity for objects
307β
308While the nested fields use the index in their `name`, use your adapter's identity mechanism to keep each object tied
309to the same rendered item.
310β
311<!-- ::start:framework -->
312β
313# React
314β
315```tsx
316array.value.map((person) => <li key={person.id}>Item fields</li>)
317```
318β
319# Preact
320β
321```tsx
322array.value.map((person) => <li key={person.id}>Item fields</li>)
323```
324β
325# Solid
326β
327```tsx
328<For each={array().value}>{() => <li>Item fields</li>}</For>
329```
330β
331# Angular
332β
333```html
334@for (person of people.api.value; track person.id) {
335<li>Item fields</li>
336}
337```
338β
339# Lit
340β
341```ts
342repeat(
343 array.value,
344 (person) => person.id,
345 () => html`<li>Item fields</li>`,
346)
347```
348β
349# Svelte
350β
351```svelte
352{#each array.value as person (person.id)}
353 <li>Item fields</li>
354{/each}
355```
356β
357# Vue
358β
359```vue
360<li v-for="person in array.value" :key="person.id">Item fields</li>
361```
362β
363<!-- ::end:framework -->
364β
365## Updating array values
366β
367Use the array field's mutation methods for structural changes. You can perform the same mutations from the form API by
368passing the field name first.
369β
370<!-- ::start:tabs variant="files" -->
371β
372```ts file="Field methods"
373// Append an item.
374field.pushValue(value)
375β
376// Insert an item at an index.
377field.insertValue(index, value)
378β
379// Remove the item at an index.
380field.removeValue(index)
381β
382// Replace the item at an index.
383field.replaceValue(index, value)
384β
385// Exchange two items.
386field.swapValues(indexA, indexB)
387β
388// Move an item from one index to another.
389field.moveValue(fromIndex, toIndex)
390β
391// Keep the items accepted by a predicate.
392field.filterValues((value, i) => isEnabled(value))
393β
394// Remove every item.
395field.clearValues()
396```
397β
398```ts file="Form methods"
399// Append an item.
400form.pushFieldValue('items', value)
401β
402// Insert an item at an index.
403form.insertFieldValue('items', index, value)
404β
405// Remove the item at an index.
406form.removeFieldValue('items', index)
407β
408// Replace the item at an index.
409form.replaceFieldValue('items', index, value)
410β
411// Exchange two items.
412form.swapFieldValues('items', indexA, indexB)
413β
414// Move an item from one index to another.
415form.moveFieldValue('items', fromIndex, toIndex)
416β
417// Keep the items accepted by a predicate.
418form.filterFieldValues('items', (value, i) => isEnabled(value))
419β
420// Remove every item.
421form.clearFieldValues('items')
422```
423β
424<!-- ::end:tabs -->
425β
426You could make these changes yourself with `handleChange`, but these helpers also take care of the registered fields
427for each item. When an item moves, its field state moves with it. When an item is removed, its field state is removed too.
428β
429A successful array mutation marks the array field as touched and dirty and causes validation by default.