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

FormApi.md

492 lines13.4 KB

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.