Open History to see the last commit
1---
2id: FormApiArrayMethods
3title: FormApiArrayMethods
4---
5β
6Defined in: [FormApi/FormApiArrayMethods.types.public.ts:322](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiArrayMethods.types.public.ts#L322)
7β
8Methods for adding, removing, moving, and filtering array field elements.
9β
10## Extended by
11β
12- [`FormApi`](FormApi.md)
13β
14## Type Parameters
15β
16### TFormData
17β
18`TFormData`
19β
20Library-managed. Do not specify explicitly.
21β
22## Properties
23β
24### clearFieldValues
25β
26```ts
27clearFieldValues: ClearFieldValuesFn<TFormData>;
28```
29β
30Defined in: [FormApi/FormApiArrayMethods.types.public.ts:410](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiArrayMethods.types.public.ts#L410)
31β
32Removes every element from an array field.
33β
34A runtime value that is not an array produces a warning and is left
35unchanged. By default, the update marks the array field as touched and
36dirty, notifies change listeners, and runs change validation.
37β
38#### Example
39β
40```ts
41// items: ['first', 'second']
42formApi.clearFieldValues('items')
43// items: []
44```
45β
46***
47β
48### filterFieldValues
49β
50```ts
51filterFieldValues: FilterFieldValuesFn<TFormData>;
52```
53β
54Defined in: [FormApi/FormApiArrayMethods.types.public.ts:465](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiArrayMethods.types.public.ts#L465)
55β
56Keeps the elements that satisfy a predicate.
57β
58`options.thisArg` sets the predicate's `this` value. A runtime value that is
59not an array produces a warning and is left unchanged. By default, the
60update marks the array field as touched and dirty, notifies change
61listeners, and runs change validation.
62β
63#### Example
64β
65```ts
66// items: [1, 2, 3, 4]
67formApi.filterFieldValues('items', (item) => item % 2 === 0)
68// items: [2, 4]
69```
70β
71***
72β
73### insertFieldValue
74β
75```ts
76insertFieldValue: InsertFieldValueFn<TFormData>;
77```
78β
79Defined in: [FormApi/FormApiArrayMethods.types.public.ts:394](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiArrayMethods.types.public.ts#L394)
80β
81Inserts an element at an index in an array field.
82β
83The index must be between `0` and `array.length`; passing `array.length`
84appends the element. An out-of-range index or a runtime value that is not
85an array produces a warning and leaves the value unchanged.
86β
87By default, the update marks the array field as touched and dirty, notifies
88change listeners, and runs change validation.
89β
90#### Example
91β
92```ts
93// items: ['first', 'second']
94formApi.insertFieldValue('items', 1, 'new item')
95// items: ['first', 'new item', 'second']
96```
97β
98***
99β
100### moveFieldValue
101β
102```ts
103moveFieldValue: MoveFieldValueFn<TFormData>;
104```
105β
106Defined in: [FormApi/FormApiArrayMethods.types.public.ts:359](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiArrayMethods.types.public.ts#L359)
107β
108Moves an element to another index in an array field.
109β
110Both indices must be between `0` and `array.length - 1`. Passing equal
111indices does nothing. Out-of-range indices or a runtime value that is not
112an array produce a warning and leave the value unchanged.
113β
114By default, the update marks the array field as touched and dirty, notifies
115change listeners, and runs change validation.
116β
117#### Example
118β
119```ts
120// items: ['first', 'second', 'third']
121formApi.moveFieldValue('items', 0, 2)
122// items: ['second', 'third', 'first']
123```
124β
125***
126β
127### pushFieldValue
128β
129```ts
130pushFieldValue: PushFieldValueFn<TFormData>;
131```
132β
133Defined in: [FormApi/FormApiArrayMethods.types.public.ts:375](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiArrayMethods.types.public.ts#L375)
134β
135Appends an element to an array field.
136β
137A runtime value that is not an array produces a warning and is left
138unchanged. By default, the update marks the array field as touched and
139dirty, notifies change listeners, and runs change validation.
140β
141#### Example
142β
143```ts
144// items: ['first', 'second']
145formApi.pushFieldValue('items', 'new item')
146// items: ['first', 'second', 'new item']
147```
148β
149***
150β
151### removeFieldValue
152β
153```ts
154removeFieldValue: RemoveFieldValueFn<TFormData>;
155```
156β
157Defined in: [FormApi/FormApiArrayMethods.types.public.ts:429](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiArrayMethods.types.public.ts#L429)
158β
159Removes an element from an array field.
160β
161The index must be between `0` and `array.length - 1`. An out-of-range index
162or a runtime value that is not an array produces a warning and leaves the
163value unchanged.
164β
165By default, the update marks the array field as touched and dirty, notifies
166change listeners, and runs change validation.
167β
168#### Example
169β
170```ts
171// items: ['first', 'second', 'third']
172formApi.removeFieldValue('items', 1)
173// items: ['first', 'third']
174```
175β
176***
177β
178### replaceFieldValue
179β
180```ts
181replaceFieldValue: ReplaceFieldValueFn<TFormData>;
182```
183β
184Defined in: [FormApi/FormApiArrayMethods.types.public.ts:448](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiArrayMethods.types.public.ts#L448)
185β
186Replaces the element at an index in an array field.
187β
188The index must be between `0` and `array.length - 1`. An out-of-range index
189or a runtime value that is not an array produces a warning and leaves the
190value unchanged.
191β
192By default, the update marks the array field as touched and dirty, notifies
193change listeners, and runs change validation.
194β
195#### Example
196β
197```ts
198// items: ['first', 'second', 'third']
199formApi.replaceFieldValue('items', 1, 'new item')
200// items: ['first', 'new item', 'third']
201```
202β
203***
204β
205### swapFieldValues
206β
207```ts
208swapFieldValues: SwapFieldValuesFn<TFormData>;
209```
210β
211Defined in: [FormApi/FormApiArrayMethods.types.public.ts:340](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiArrayMethods.types.public.ts#L340)
212β
213Swaps two elements in an array field.
214β
215Both indices must be between `0` and `array.length - 1`. Passing equal
216indices does nothing. Out-of-range indices or a runtime value that is not
217an array produce a warning and leave the value unchanged.
218β
219By default, the update marks the array field as touched and dirty, notifies
220change listeners, and runs change validation.
221β
222#### Example
223β
224```ts
225// items: ['first', 'second', 'third']
226formApi.swapFieldValues('items', 0, 2)
227// items: ['third', 'second', 'first']
228```