Open History to see the last commit
1---
2id: FormApi
3title: FormApi
4---
5β
6Defined in: [FormApi/FormApi.public.ts:638](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L638)
7β
8Core API for reading and updating state, validating values, and handling
9submission.
10β
11Framework adapters compose this interface with framework-specific helpers.
12β
13## Extends
14β
15- [`FormApiFieldMethods`](FormApiFieldMethods.md)\<`TFormData`\>.[`FormApiArrayMethods`](FormApiArrayMethods.md)\<`TFormData`\>
16β
17## Type Parameters
18β
19### TFormData
20β
21`TFormData`
22β
23Library-managed. Do not specify explicitly.
24β
25### TFormErrorTypes
26β
27`TFormErrorTypes` *extends* [`FormErrorTypes`](FormErrorTypes.md)
28β
29Library-managed. Do not specify explicitly.
30β
31## Properties
32β
33### atom
34β
35```ts
36atom: ReadonlyAtom<FormState<TFormData, TFormErrorTypes>>;
37```
38β
39Defined in: [FormApi/FormApi.public.ts:649](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L649)
40β
41Read-only atom containing reactive `FormState` snapshots.
42β
43Subscribe to this atom to observe state changes. For an imperative read,
44use `state`.
45β
46***
47β
48### clearFieldValues
49β
50```ts
51clearFieldValues: ClearFieldValuesFn<TFormData>;
52```
53β
54Defined in: [FormApi/FormApiArrayMethods.types.public.ts:410](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiArrayMethods.types.public.ts#L410)
55β
56Removes every element from an array field.
57β
58A runtime value that is not an array produces a warning and is left
59unchanged. By default, the update marks the array field as touched and
60dirty, notifies change listeners, and runs change validation.
61β
62#### Example
63β
64```ts
65// items: ['first', 'second']
66formApi.clearFieldValues('items')
67// items: []
68```
69β
70#### Inherited from
71β
72[`FormApiArrayMethods`](FormApiArrayMethods.md).[`clearFieldValues`](FormApiArrayMethods.md#clearfieldvalues)
73β
74***
75β
76### defaultValues
77β
78```ts
79readonly defaultValues: TFormData;
80```
81β
82Defined in: [FormApi/FormApi.public.ts:653](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L653)
83β
84The current baseline values used by `reset()` and `isDefaultValue`.
85β
86***
87β
88### filterFieldValues
89β
90```ts
91filterFieldValues: FilterFieldValuesFn<TFormData>;
92```
93β
94Defined in: [FormApi/FormApiArrayMethods.types.public.ts:465](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiArrayMethods.types.public.ts#L465)
95β
96Keeps the elements that satisfy a predicate.
97β
98`options.thisArg` sets the predicate's `this` value. A runtime value that is
99not an array produces a warning and is left unchanged. By default, the
100update marks the array field as touched and dirty, notifies change
101listeners, and runs change validation.
102β
103#### Example
104β
105```ts
106// items: [1, 2, 3, 4]
107formApi.filterFieldValues('items', (item) => item % 2 === 0)
108// items: [2, 4]
109```
110β
111#### Inherited from
112β
113[`FormApiArrayMethods`](FormApiArrayMethods.md).[`filterFieldValues`](FormApiArrayMethods.md#filterfieldvalues)
114β
115***
116β
117### formId
118β
119```ts
120readonly formId: string;
121```
122β
123Defined in: [FormApi/FormApi.public.ts:660](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L660)
124β
125Stable identifier supplied by `FormOptions.formId` or generated at
126creation.
127β
128It is preserved across option updates until a new `formId` is supplied.
129β
130***
131β
132### getFieldValue
133β
134```ts
135getFieldValue: GetFieldValueFn<TFormData>;
136```
137β
138Defined in: [FormApi/FormApiFieldMethods.types.public.ts:114](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiFieldMethods.types.public.ts#L114)
139β
140Reads the current value at a field path.
141β
142This is a read-only operation and does not create a `FieldApi` for the path.
143β
144#### Example
145β
146```ts
147const name = formApi.getFieldValue('profile.name')
148```
149β
150#### Returns
151β
152The current value at the path, or `undefined` when the path cannot
153be resolved at runtime.
154β
155#### Inherited from
156β
157[`FormApiFieldMethods`](FormApiFieldMethods.md).[`getFieldValue`](FormApiFieldMethods.md#getfieldvalue)
158β
159***
160β
161### handleSubmit
162β
163```ts
164handleSubmit: HandleSubmitFn<TFormData>;
165```
166β
167Defined in: [FormApi/FormApi.public.ts:698](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L698)
168β
169Runs submission validation and submits current values when validation
170succeeds.
171β
172Registered fields are marked touched, field validators run before form
173validators, and `onSubmit` is awaited only when validation succeeds.
174Validation error results and errors returned by `onSubmit` through
175`createValidationError` are stored as error state. `onSubmitInvalid` is
176awaited after a failed attempt.
177β
178Calls made while an attempt is in progress return the same promise instead
179of starting another attempt.
180β
181The returned promise resolves to the error results produced by field and
182form validation, plus any validation error returned by `onSubmit` through
183`createValidationError`. The array is empty if none are produced.
184β
185***
186β
187### insertFieldValue
188β
189```ts
190insertFieldValue: InsertFieldValueFn<TFormData>;
191```
192β
193Defined in: [FormApi/FormApiArrayMethods.types.public.ts:394](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiArrayMethods.types.public.ts#L394)
194β
195Inserts an element at an index in an array field.
196β
197The index must be between `0` and `array.length`; passing `array.length`
198appends the element. An out-of-range index or a runtime value that is not
199an array produces a warning and leaves the value unchanged.
200β
201By default, the update marks the array field as touched and dirty, notifies
202change listeners, and runs change validation.
203β
204#### Example
205β
206```ts
207// items: ['first', 'second']
208formApi.insertFieldValue('items', 1, 'new item')
209// items: ['first', 'new item', 'second']
210```
211β
212#### Inherited from
213β
214[`FormApiArrayMethods`](FormApiArrayMethods.md).[`insertFieldValue`](FormApiArrayMethods.md#insertfieldvalue)
215β
216***
217β
218### moveFieldValue
219β
220```ts
221moveFieldValue: MoveFieldValueFn<TFormData>;
222```
223β
224Defined in: [FormApi/FormApiArrayMethods.types.public.ts:359](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiArrayMethods.types.public.ts#L359)
225β
226Moves an element to another index in an array field.
227β
228Both indices must be between `0` and `array.length - 1`. Passing equal
229indices does nothing. Out-of-range indices or a runtime value that is not
230an array produce a warning and leave the value unchanged.
231β
232By default, the update marks the array field as touched and dirty, notifies
233change listeners, and runs change validation.
234β
235#### Example
236β
237```ts
238// items: ['first', 'second', 'third']
239formApi.moveFieldValue('items', 0, 2)
240// items: ['second', 'third', 'first']
241```
242β
243#### Inherited from
244β
245[`FormApiArrayMethods`](FormApiArrayMethods.md).[`moveFieldValue`](FormApiArrayMethods.md#movefieldvalue)
246β
247***
248β
249### pushFieldValue
250β
251```ts
252pushFieldValue: PushFieldValueFn<TFormData>;
253```
254β
255Defined in: [FormApi/FormApiArrayMethods.types.public.ts:375](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiArrayMethods.types.public.ts#L375)
256β
257Appends an element to an array field.
258β
259A runtime value that is not an array produces a warning and is left
260unchanged. By default, the update marks the array field as touched and
261dirty, notifies change listeners, and runs change validation.
262β
263#### Example
264β
265```ts
266// items: ['first', 'second']
267formApi.pushFieldValue('items', 'new item')
268// items: ['first', 'second', 'new item']
269```
270β
271#### Inherited from
272β
273[`FormApiArrayMethods`](FormApiArrayMethods.md).[`pushFieldValue`](FormApiArrayMethods.md#pushfieldvalue)
274β
275***
276β
277### removeFieldValue
278β
279```ts
280removeFieldValue: RemoveFieldValueFn<TFormData>;
281```
282β
283Defined in: [FormApi/FormApiArrayMethods.types.public.ts:429](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiArrayMethods.types.public.ts#L429)
284β
285Removes an element from an array field.
286β
287The index must be between `0` and `array.length - 1`. An out-of-range index
288or a runtime value that is not an array produces a warning and leaves the
289value unchanged.
290β
291By default, the update marks the array field as touched and dirty, notifies
292change listeners, and runs change validation.
293β
294#### Example
295β
296```ts
297// items: ['first', 'second', 'third']
298formApi.removeFieldValue('items', 1)
299// items: ['first', 'third']
300```
301β
302#### Inherited from
303β
304[`FormApiArrayMethods`](FormApiArrayMethods.md).[`removeFieldValue`](FormApiArrayMethods.md#removefieldvalue)
305β
306***
307β
308### replaceFieldValue
309β
310```ts
311replaceFieldValue: ReplaceFieldValueFn<TFormData>;
312```
313β
314Defined in: [FormApi/FormApiArrayMethods.types.public.ts:448](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiArrayMethods.types.public.ts#L448)
315β
316Replaces the element at an index in an array field.
317β
318The index must be between `0` and `array.length - 1`. An out-of-range index
319or a runtime value that is not an array produces a warning and leaves the
320value unchanged.
321β
322By default, the update marks the array field as touched and dirty, notifies
323change listeners, and runs change validation.
324β
325#### Example
326β
327```ts
328// items: ['first', 'second', 'third']
329formApi.replaceFieldValue('items', 1, 'new item')
330// items: ['first', 'new item', 'third']
331```
332β
333#### Inherited from
334β
335[`FormApiArrayMethods`](FormApiArrayMethods.md).[`replaceFieldValue`](FormApiArrayMethods.md#replacefieldvalue)
336β
337***
338β
339### reset
340β
341```ts
342reset: ResetFn<TFormData>;
343```
344β
345Defined in: [FormApi/FormApi.public.ts:713](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L713)
346β
347Reset form values, metadata, validation state, and mounted fields.
348β
349`reset()` restores the current `defaultValues`.
350β
351`reset(values)` sets the current values and also updates `defaultValues`
352to those values. This can apply expected values immediately while fresh
353data is fetched from the backend.
354β
355Results from validation or submission work pending at reset are discarded.
356β
357Pass `{ updateDefaultValues: false }` as the options argument to preserve
358the existing `defaultValues` when supplying values.
359β
360***
361β
362### resetField
363β
364```ts
365resetField: ResetFieldFn<TFormData>;
366```
367β
368Defined in: [FormApi/FormApiFieldMethods.types.public.ts:131](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiFieldMethods.types.public.ts#L131)
369β
370Restores a field path from `defaultValues` and resets state for its field
371subtree.
372β
373Existing `FieldApi` instances at or below the path remain mounted.
374Form-wide dirty history remains unchanged; use `formApi.reset()` to clear
375it.
376β
377#### Example
378β
379```ts
380formApi.setFieldValue('profile.name', 'Grace')
381formApi.resetField('profile.name')
382// `profile.name` is restored from `defaultValues`.
383```
384β
385#### Inherited from
386β
387[`FormApiFieldMethods`](FormApiFieldMethods.md).[`resetField`](FormApiFieldMethods.md#resetfield)
388β
389***
390β
391### setFieldValue
392β
393```ts
394setFieldValue: SetFieldValueFn<TFormData>;
395```
396β
397Defined in: [FormApi/FormApiFieldMethods.types.public.ts:99](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiFieldMethods.types.public.ts#L99)
398β
399Updates the current value at a field path.
400β
401The next value may be supplied directly or calculated from the current
402value. By default, the update marks the field as touched and dirty,
403notifies change listeners, and runs change validation.
404β
405#### Example
406β
407```ts
408formApi.setFieldValue('profile.name', 'Ada')
409formApi.setFieldValue('visitCount', (count) => count + 1)
410```
411β
412#### Inherited from
413β
414[`FormApiFieldMethods`](FormApiFieldMethods.md).[`setFieldValue`](FormApiFieldMethods.md#setfieldvalue)
415β
416***
417β
418### state
419β
420```ts
421readonly state: FormState<TFormData, TFormErrorTypes>;
422```
423β
424Defined in: [FormApi/FormApi.public.ts:651](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L651)
425β
426Current values, validation status, and submission metadata.
427β
428***
429β
430### swapFieldValues
431β
432```ts
433swapFieldValues: SwapFieldValuesFn<TFormData>;
434```
435β
436Defined in: [FormApi/FormApiArrayMethods.types.public.ts:340](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApiArrayMethods.types.public.ts#L340)
437β
438Swaps two elements in an array field.
439β
440Both indices must be between `0` and `array.length - 1`. Passing equal
441indices does nothing. Out-of-range indices or a runtime value that is not
442an array produce a warning and leave the value unchanged.
443β
444By default, the update marks the array field as touched and dirty, notifies
445change listeners, and runs change validation.
446β
447#### Example
448β
449```ts
450// items: ['first', 'second', 'third']
451formApi.swapFieldValues('items', 0, 2)
452// items: ['third', 'second', 'first']
453```
454β
455#### Inherited from
456β
457[`FormApiArrayMethods`](FormApiArrayMethods.md).[`swapFieldValues`](FormApiArrayMethods.md#swapfieldvalues)
458β
459***
460β
461### validate
462β
463```ts
464validate: (signal) => Promise<FormValidationError<TFormData>[]>;
465```
466β
467Defined in: [FormApi/FormApi.public.ts:677](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L677)
468β
469Runs form-level validators enabled for the specified `'change'` or
470`'blur'` trigger.
471β
472Prefer configured validator triggers for change and blur validation, and
473use `handleSubmit()` for submission validation. Calling this method
474directly is rarely necessary.
475β
476Results update form-level errors and any errors routed to fields.
477Field-level validators are not run by this method.
478β
479#### Parameters
480β
481##### signal
482β
483[`ConfigurableValidationTrigger`](../type-aliases/ConfigurableValidationTrigger.md)
484β
485The trigger used to select validators.
486β
487#### Returns
488β
489`Promise`\<[`FormValidationError`](../type-aliases/FormValidationError.md)\<`TFormData`\>[]\>
490β
491A promise resolving to each error result from the validators that
492ran. Unlike `state.errors`, these results are not flattened.