Skip to content
Source
Sign inSign up
TanStack/form
Open History to see the last commit

FormApiArrayMethods.md

228 lines6.1 KB

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```