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

FormState.md

233 lines5.9 KB

1---
2id: FormState
3title: FormState
4---
5​
6Defined in: [FormApi/FormApi.public.ts:426](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L426)
7​
8A snapshot of current values, validation status, and submission metadata.
9​
10Read the latest snapshot from `formApi.state` or subscribe to
11`formApi.atom`.
12​
13## Type Parameters
14​
15### TFormData
16​
17`TFormData`
18​
19Library-managed. Do not specify explicitly.
20​
21### TFormErrorTypes
22​
23`TFormErrorTypes` *extends* [`FormErrorTypes`](FormErrorTypes.md)
24​
25Library-managed. Do not specify explicitly.
26​
27## Properties
28​
29### canSubmit
30​
31```ts
32canSubmit: boolean;
33```
34​
35Defined in: [FormApi/FormApi.public.ts:504](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L504)
36​
37Whether no submission is running and validation state has no known errors.
38​
39This is optimistic: validation does not need to have run, and pending
40validation alone does not make it `false`. `handleSubmit()` still runs
41submission validation.
42​
43* Equivalent to `isValid && !isSubmitting`.
44​
45***
46​
47### errors
48​
49```ts
50errors: FormErrors<TFormErrorTypes>;
51```
52​
53Defined in: [FormApi/FormApi.public.ts:478](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L478)
54​
55Form-level errors from validators and `onSubmit`.
56​
57Errors are flattened in validator order, with `onSubmit` errors last.
58Errors routed to fields are exposed through the corresponding field APIs
59and are not included here.
60​
61***
62​
63### isDefaultValue
64​
65```ts
66isDefaultValue: boolean;
67```
68​
69Defined in: [FormApi/FormApi.public.ts:470](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L470)
70​
71Whether current values deeply match `formApi.defaultValues`.
72​
73Unlike `isDirty` and `isPristine`, this compares current values with their
74defaults rather than tracking whether edits have occurred. Reverting an
75edit can make it `true` while `isDirty` remains `true`.
76​
77***
78​
79### isDirty
80​
81```ts
82isDirty: boolean;
83```
84​
85Defined in: [FormApi/FormApi.public.ts:451](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L451)
86​
87Whether a value update has marked state as dirty.
88​
89This records whether a dirty-marking update has occurred, not whether
90current values match their defaults. Once `true`, it remains `true` even if
91values return to their defaults. `formApi.reset()` clears it.
92​
93* Equivalent to `!isPristine`.
94* Use `isDefaultValue` to check whether current values match their defaults.
95​
96***
97​
98### isInvalid
99​
100```ts
101isInvalid: boolean;
102```
103​
104Defined in: [FormApi/FormApi.public.ts:494](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L494)
105​
106Whether validation state contains at least one form- or field-level error.
107​
108This is the exact inverse of `isValid`. Field `errorVisibility` does not
109affect it.
110​
111* Equivalent to `!isValid`.
112​
113***
114​
115### isPristine
116​
117```ts
118isPristine: boolean;
119```
120​
121Defined in: [FormApi/FormApi.public.ts:462](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L462)
122​
123Whether state has not been marked dirty.
124​
125This records whether a dirty-marking update has occurred, not whether
126current values match their defaults. Once `false`, it remains `false` even
127if values return to their defaults. `formApi.reset()` restores it.
128​
129* Equivalent to `!isDirty`.
130* Use `isDefaultValue` to check whether current values match their defaults.
131​
132***
133​
134### isSubmitSuccessful
135​
136```ts
137isSubmitSuccessful: boolean;
138```
139​
140Defined in: [FormApi/FormApi.public.ts:519](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L519)
141​
142Whether the latest completed submission finished without validation errors
143or an `onSubmit` failure.
144​
145It starts as `false`, updates when an attempt finishes, and is cleared by
146`formApi.reset()`.
147​
148***
149​
150### isSubmitting
151​
152```ts
153isSubmitting: boolean;
154```
155​
156Defined in: [FormApi/FormApi.public.ts:511](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L511)
157​
158Whether a submission attempt is in progress.
159​
160This includes submission validation and the time spent awaiting `onSubmit`
161or `onSubmitInvalid`.
162​
163***
164​
165### isTouched
166​
167```ts
168isTouched: boolean;
169```
170​
171Defined in: [FormApi/FormApi.public.ts:440](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L440)
172​
173Whether at least one field is currently touched.
174​
175Field changes mark fields as touched by default, and submission marks all
176registered fields as touched. Resets clear the touched state.
177​
178***
179​
180### isValid
181​
182```ts
183isValid: boolean;
184```
185​
186Defined in: [FormApi/FormApi.public.ts:485](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L485)
187​
188Whether validation state contains no form- or field-level errors.
189​
190* Equivalent to `!isInvalid`.
191* A field error hidden by `errorVisibility` still makes this `false`.
192​
193***
194​
195### isValidating
196​
197```ts
198isValidating: boolean;
199```
200​
201Defined in: [FormApi/FormApi.public.ts:526](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L526)
202​
203Whether any form-, group-, or field-level validation is pending.
204​
205It remains `true` until all concurrent validation work finishes or is
206canceled. Pending validation does not by itself make `canSubmit` `false`.
207​
208***
209​
210### submissionAttempts
211​
212```ts
213submissionAttempts: number;
214```
215​
216Defined in: [FormApi/FormApi.public.ts:533](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L533)
217​
218Number of submission attempts started since the last reset.
219​
220An attempt is counted before validation begins, whether it succeeds or
221fails. `formApi.reset()` returns the count to `0`.
222​
223***
224​
225### values
226​
227```ts
228values: TFormData;
229```
230​
231Defined in: [FormApi/FormApi.public.ts:433](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L433)
232​
233Current values after field edits, resets, or default-value updates.