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

FormState.md

496 lines10.8 KB

1---
2id: FormState
3title: FormState
4---
5​
6# Interface: FormState\<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer\>
7​
8Defined in: [packages/form-core/src/FormApi.ts:718](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L718)
9​
10An object representing the current state of the form.
11​
12## Extends
13​
14- [`BaseFormState`](../type-aliases/BaseFormState.md)\<`TFormData`, `TOnMount`, `TOnChange`, `TOnChangeAsync`, `TOnBlur`, `TOnBlurAsync`, `TOnSubmit`, `TOnSubmitAsync`, `TOnDynamic`, `TOnDynamicAsync`, `TOnServer`\>.[`DerivedFormState`](../type-aliases/DerivedFormState.md)\<`TFormData`, `TOnMount`, `TOnChange`, `TOnChangeAsync`, `TOnBlur`, `TOnBlurAsync`, `TOnSubmit`, `TOnSubmitAsync`, `TOnDynamic`, `TOnDynamicAsync`, `TOnServer`\>
15​
16## Type Parameters
17​
18### TFormData
19​
20`TFormData`
21​
22### TOnMount
23​
24`TOnMount` *extends* `undefined` \| `FormValidateOrFn`\<`TFormData`\>
25​
26### TOnChange
27​
28`TOnChange` *extends* `undefined` \| `FormValidateOrFn`\<`TFormData`\>
29​
30### TOnChangeAsync
31​
32`TOnChangeAsync` *extends* `undefined` \| `FormAsyncValidateOrFn`\<`TFormData`\>
33​
34### TOnBlur
35​
36`TOnBlur` *extends* `undefined` \| `FormValidateOrFn`\<`TFormData`\>
37​
38### TOnBlurAsync
39​
40`TOnBlurAsync` *extends* `undefined` \| `FormAsyncValidateOrFn`\<`TFormData`\>
41​
42### TOnSubmit
43​
44`TOnSubmit` *extends* `undefined` \| `FormValidateOrFn`\<`TFormData`\>
45​
46### TOnSubmitAsync
47​
48`TOnSubmitAsync` *extends* `undefined` \| `FormAsyncValidateOrFn`\<`TFormData`\>
49​
50### TOnDynamic
51​
52`TOnDynamic` *extends* `undefined` \| `FormValidateOrFn`\<`TFormData`\>
53​
54### TOnDynamicAsync
55​
56`TOnDynamicAsync` *extends* `undefined` \| `FormAsyncValidateOrFn`\<`TFormData`\>
57​
58### TOnServer
59​
60`TOnServer` *extends* `undefined` \| `FormAsyncValidateOrFn`\<`TFormData`\>
61​
62## Properties
63​
64### \_force\_re\_eval?
65​
66```ts
67optional _force_re_eval: boolean;
68```
69​
70Defined in: [packages/form-core/src/FormApi.ts:623](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L623)
71​
72@private, used to force a re-evaluation of the form state when options change
73​
74#### Inherited from
75​
76```ts
77BaseFormState._force_re_eval
78```
79​
80***
81​
82### canSubmit
83​
84```ts
85canSubmit: boolean;
86```
87​
88Defined in: [packages/form-core/src/FormApi.ts:711](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L711)
89​
90A boolean indicating if the form can be submitted based on its current state.
91​
92#### Inherited from
93​
94```ts
95DerivedFormState.canSubmit
96```
97​
98***
99​
100### errorMap
101​
102```ts
103errorMap: ValidationErrorMap<UnwrapFormValidateOrFn<TOnMount>, UnwrapFormValidateOrFn<TOnChange>, UnwrapFormAsyncValidateOrFn<TOnChangeAsync>, UnwrapFormValidateOrFn<TOnBlur>, UnwrapFormAsyncValidateOrFn<TOnBlurAsync>, UnwrapFormValidateOrFn<TOnSubmit>, UnwrapFormAsyncValidateOrFn<TOnSubmitAsync>, UnwrapFormValidateOrFn<TOnDynamic>, UnwrapFormAsyncValidateOrFn<TOnDynamicAsync>, UnwrapFormAsyncValidateOrFn<TOnServer>>;
104```
105​
106Defined in: [packages/form-core/src/FormApi.ts:567](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L567)
107​
108The error map for the form itself.
109​
110#### Inherited from
111​
112```ts
113BaseFormState.errorMap
114```
115​
116***
117​
118### errors
119​
120```ts
121errors: (
122 | UnwrapFormValidateOrFn<TOnMount>
123 | UnwrapFormValidateOrFn<TOnChange>
124 | UnwrapFormAsyncValidateOrFn<TOnChangeAsync>
125 | UnwrapFormValidateOrFn<TOnBlur>
126 | UnwrapFormAsyncValidateOrFn<TOnBlurAsync>
127 | UnwrapFormValidateOrFn<TOnSubmit>
128 | UnwrapFormAsyncValidateOrFn<TOnSubmitAsync>
129 | UnwrapFormValidateOrFn<TOnDynamic>
130 | UnwrapFormAsyncValidateOrFn<TOnDynamicAsync>
131 | UnwrapFormAsyncValidateOrFn<TOnServer>)[];
132```
133​
134Defined in: [packages/form-core/src/FormApi.ts:664](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L664)
135​
136The error array for the form itself.
137​
138#### Inherited from
139​
140```ts
141DerivedFormState.errors
142```
143​
144***
145​
146### fieldMeta
147​
148```ts
149fieldMeta: Partial<Record<DeepKeys<TFormData>, AnyFieldMeta>>;
150```
151​
152Defined in: [packages/form-core/src/FormApi.ts:715](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L715)
153​
154A record of field metadata for each field in the form.
155​
156#### Inherited from
157​
158```ts
159DerivedFormState.fieldMeta
160```
161​
162***
163​
164### fieldMetaBase
165​
166```ts
167fieldMetaBase: Partial<Record<DeepKeys<TFormData>, AnyFieldMetaBase>>;
168```
169​
170Defined in: [packages/form-core/src/FormApi.ts:586](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L586)
171​
172A record of field metadata for each field in the form, not including the derived properties, like `errors` and such
173​
174#### Inherited from
175​
176```ts
177BaseFormState.fieldMetaBase
178```
179​
180***
181​
182### isBlurred
183​
184```ts
185isBlurred: boolean;
186```
187​
188Defined in: [packages/form-core/src/FormApi.ts:691](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L691)
189​
190A boolean indicating if any of the form fields have been blurred.
191​
192#### Inherited from
193​
194```ts
195DerivedFormState.isBlurred
196```
197​
198***
199​
200### isDefaultValue
201​
202```ts
203isDefaultValue: boolean;
204```
205​
206Defined in: [packages/form-core/src/FormApi.ts:703](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L703)
207​
208A boolean indicating if all of the form's fields are the same as default values.
209​
210#### Inherited from
211​
212```ts
213DerivedFormState.isDefaultValue
214```
215​
216***
217​
218### isDirty
219​
220```ts
221isDirty: boolean;
222```
223​
224Defined in: [packages/form-core/src/FormApi.ts:695](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L695)
225​
226A boolean indicating if any of the form's fields' values have been modified by the user. Evaluates `true` if the user have modified at least one of the fields. Opposite of `isPristine`.
227​
228#### Inherited from
229​
230```ts
231DerivedFormState.isDirty
232```
233​
234***
235​
236### isFieldsValid
237​
238```ts
239isFieldsValid: boolean;
240```
241​
242Defined in: [packages/form-core/src/FormApi.ts:683](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L683)
243​
244A boolean indicating if all the form fields are valid. Evaluates `true` if there are no field errors.
245​
246#### Inherited from
247​
248```ts
249DerivedFormState.isFieldsValid
250```
251​
252***
253​
254### isFieldsValidating
255​
256```ts
257isFieldsValidating: boolean;
258```
259​
260Defined in: [packages/form-core/src/FormApi.ts:679](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L679)
261​
262A boolean indicating if any of the form fields are currently validating.
263​
264#### Inherited from
265​
266```ts
267DerivedFormState.isFieldsValidating
268```
269​
270***
271​
272### isFormValid
273​
274```ts
275isFormValid: boolean;
276```
277​
278Defined in: [packages/form-core/src/FormApi.ts:660](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L660)
279​
280A boolean indicating if the form is valid.
281​
282#### Inherited from
283​
284```ts
285DerivedFormState.isFormValid
286```
287​
288***
289​
290### isFormValidating
291​
292```ts
293isFormValidating: boolean;
294```
295​
296Defined in: [packages/form-core/src/FormApi.ts:656](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L656)
297​
298A boolean indicating if the form is currently validating.
299​
300#### Inherited from
301​
302```ts
303DerivedFormState.isFormValidating
304```
305​
306***
307​
308### isPristine
309​
310```ts
311isPristine: boolean;
312```
313​
314Defined in: [packages/form-core/src/FormApi.ts:699](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L699)
315​
316A boolean indicating if none of the form's fields' values have been modified by the user. Evaluates `true` if the user have not modified any of the fields. Opposite of `isDirty`.
317​
318#### Inherited from
319​
320```ts
321DerivedFormState.isPristine
322```
323​
324***
325​
326### isSubmitSuccessful
327​
328```ts
329isSubmitSuccessful: boolean;
330```
331​
332Defined in: [packages/form-core/src/FormApi.ts:619](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L619)
333​
334A boolean indicating if the last submission was successful.
335​
336#### Inherited from
337​
338```ts
339BaseFormState.isSubmitSuccessful
340```
341​
342***
343​
344### isSubmitted
345​
346```ts
347isSubmitted: boolean;
348```
349​
350Defined in: [packages/form-core/src/FormApi.ts:607](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L607)
351​
352A boolean indicating if the `onSubmit` function has completed successfully.
353​
354Goes back to `false` at each new submission attempt.
355​
356Note: you can use isSubmitting to check if the form is currently submitting.
357​
358#### Inherited from
359​
360```ts
361BaseFormState.isSubmitted
362```
363​
364***
365​
366### isSubmitting
367​
368```ts
369isSubmitting: boolean;
370```
371​
372Defined in: [packages/form-core/src/FormApi.ts:599](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L599)
373​
374A boolean indicating if the form is currently in the process of being submitted after `handleSubmit` is called.
375​
376Goes back to `false` when submission completes for one of the following reasons:
377- the validation step returned errors.
378- the `onSubmit` function has completed.
379​
380Note: if you're running async operations in your `onSubmit` function make sure to await them to ensure `isSubmitting` is set to `false` only when the async operation completes.
381​
382This is useful for displaying loading indicators or disabling form inputs during submission.
383​
384#### Inherited from
385​
386```ts
387BaseFormState.isSubmitting
388```
389​
390***
391​
392### isTouched
393​
394```ts
395isTouched: boolean;
396```
397​
398Defined in: [packages/form-core/src/FormApi.ts:687](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L687)
399​
400A boolean indicating if any of the form fields have been touched.
401​
402#### Inherited from
403​
404```ts
405DerivedFormState.isTouched
406```
407​
408***
409​
410### isValid
411​
412```ts
413isValid: boolean;
414```
415​
416Defined in: [packages/form-core/src/FormApi.ts:707](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L707)
417​
418A boolean indicating if the form and all its fields are valid. Evaluates `true` if there are no errors.
419​
420#### Inherited from
421​
422```ts
423DerivedFormState.isValid
424```
425​
426***
427​
428### isValidating
429​
430```ts
431isValidating: boolean;
432```
433​
434Defined in: [packages/form-core/src/FormApi.ts:611](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L611)
435​
436A boolean indicating if the form or any of its fields are currently validating.
437​
438#### Inherited from
439​
440```ts
441BaseFormState.isValidating
442```
443​
444***
445​
446### submissionAttempts
447​
448```ts
449submissionAttempts: number;
450```
451​
452Defined in: [packages/form-core/src/FormApi.ts:615](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L615)
453​
454A counter for tracking the number of submission attempts.
455​
456#### Inherited from
457​
458```ts
459BaseFormState.submissionAttempts
460```
461​
462***
463​
464### validationMetaMap
465​
466```ts
467validationMetaMap: Record<ValidationErrorMapKeys, ValidationMeta | undefined>;
468```
469​
470Defined in: [packages/form-core/src/FormApi.ts:582](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L582)
471​
472An internal mechanism used for keeping track of validation logic in a form.
473​
474#### Inherited from
475​
476```ts
477BaseFormState.validationMetaMap
478```
479​
480***
481​
482### values
483​
484```ts
485values: TFormData;
486```
487​
488Defined in: [packages/form-core/src/FormApi.ts:563](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L563)
489​
490The current values of the form fields.
491​
492#### Inherited from
493​
494```ts
495BaseFormState.values
496```