Open History to see the last commit
1---
2id: FormOptions
3title: FormOptions
4---
5β
6Defined in: [FormApi/FormApi.public.ts:262](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L262)
7β
8Configures initial values, validation, listeners, and submission.
9β
10Pass these options to a framework adapter's form creation API. Use
11`formOptions` when declaring them separately so data and validator types
12remain inferred.
13β
14## Example
15β
16```ts
17const profileFormOptions = formOptions({
18 defaultValues: { name: '' },
19 onSubmit: async ({ value }) => {
20 await saveProfile(value)
21 },
22})
23```
24β
25## Type Parameters
26β
27### TFormData
28β
29`TFormData`
30β
31Library-managed. Do not specify explicitly.
32β
33### TFormValidators
34β
35`TFormValidators` *extends* [`FormValidators`](../type-aliases/FormValidators.md)\<`TFormData`\>
36β
37Library-managed. Do not specify explicitly.
38β
39### TSubmitReturn
40β
41`TSubmitReturn`
42β
43Library-managed. Do not specify explicitly.
44β
45### TComponents
46β
47`TComponents`
48β
49Library-managed. Do not specify explicitly.
50β
51## Properties
52β
53### \[formOptionsComponentsSymbol\]?
54β
55```ts
56readonly optional [formOptionsComponentsSymbol]?: TComponents;
57```
58β
59Defined in: [FormApi/FormApi.public.ts:268](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L268)
60β
61***
62β
63### defaultValues
64β
65```ts
66defaultValues: TFormData;
67```
68β
69Defined in: [FormApi/FormApi.public.ts:290](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L290)
70β
71Initial values and the source of the inferred data shape.
72β
73They also define the reset baseline and what `isDefaultValue` compares
74against.
75β
76**Async initial values:** The passed value may change over time. While data
77is loading, pass fallback values containing the complete data shape, then
78pass the resolved values when they become available.
79β
80When this option changes, untouched top-level values adopt the new defaults
81while values under touched top-level fields are preserved.
82β
83***
84β
85### errorVisibility?
86β
87```ts
88optional errorVisibility?: ErrorVisibility<TFormData, ToFormErrorTypes<TFormValidators, unknown>>;
89```
90β
91Defined in: [FormApi/FormApi.public.ts:305](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L305)
92β
93Controls when fields expose validation errors through public state.
94β
95This is the default policy for every field. A field can override it with a field-level
96`errorVisibility` option.
97β
98When omitted, errors are always exposed.
99β
100#### Example
101β
102```ts
103errorVisibility: ({ state, fieldState }) =>
104 fieldState.meta.isBlurred || state.submissionAttempts > 0,
105```
106β
107***
108β
109### formId?
110β
111```ts
112optional formId?: string;
113```
114β
115Defined in: [FormApi/FormApi.public.ts:276](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L276)
116β
117A stable identifier for this form.
118β
119When omitted, an identifier is generated and preserved across option
120updates until a new `formId` is supplied. Read the supplied or generated
121identifier from `formApi.formId`.
122β
123***
124β
125### listeners?
126β
127```ts
128optional listeners?: FormListeners<TFormData, ToFormErrorTypes<TFormValidators, unknown>>;
129```
130β
131Defined in: [FormApi/FormApi.public.ts:352](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L352)
132β
133Listener configurations for change, blur, submit, mount, and reset events.
134β
135Matching listeners are evaluated in array order. Their return values are
136ignored, and returned promises are not awaited.
137β
138#### Example
139β
140```ts
141listeners: [
142 {
143 triggers: ['change'],
144 triggerDebounceMs: 200,
145 run: ({ value }) => {
146 saveDraft(value)
147 },
148 },
149],
150```
151β
152***
153β
154### onSubmit?
155β
156```ts
157optional onSubmit?: FormSubmitFn<TFormData, TFormValidators, TSubmitReturn>;
158```
159β
160Defined in: [FormApi/FormApi.public.ts:389](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L389)
161β
162Called after submission validation succeeds.
163β
164Return an error created with `createValidationError` or `parseIssues` to
165mark the submission as invalid. A returned promise is awaited before
166submission finishes. If the callback throws, `onSubmitInvalid` is called.
167β
168#### Example
169β
170```ts
171{
172 // ...
173 onSubmit: async ({ value }) => {
174 await saveUser(value)
175 },
176}
177```
178β
179***
180β
181### onSubmitInvalid?
182β
183```ts
184optional onSubmitInvalid?: (context) => void | Promise<void>;
185```
186β
187Defined in: [FormApi/FormApi.public.ts:409](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L409)
188β
189Called after an invalid submission is detected.
190β
191This includes validation failures, errors returned from `onSubmit`, and
192exceptions thrown during validation or submission. A returned promise is
193awaited before submission finishes.
194β
195#### Parameters
196β
197##### context
198β
199[`FormSubmitInvalidContext`](FormSubmitInvalidContext.md)\<`TFormData`, [`ToFormErrorTypes`](../type-aliases/ToFormErrorTypes.md)\<`TFormValidators`, `unknown`\>\>
200β
201#### Returns
202β
203`void` \| `Promise`\<`void`\>
204β
205#### Example
206β
207```ts
208{
209 // ...
210 onSubmitInvalid: () => {
211 document
212 .querySelector<HTMLElement>('[aria-invalid="true"]')
213 ?.focus()
214 },
215}
216```
217β
218***
219β
220### serverState?
221β
222```ts
223optional serverState?:
224 | ServerFormState<NoInfer<TFormData>, NoInfer<TFormValidators>>
225 | null;
226```
227β
228Defined in: [FormApi/FormApi.public.ts:368](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L368)
229β
230Server-validation state supplied by a server or SSR adapter during
231hydration.
232β
233Pass a failed result's `serverState` through unchanged. Constructing or
234mutating this state directly is discouraged.
235β
236#### Example
237β
238```ts
239serverState: failedResult.serverState,
240```
241β
242***
243β
244### validators?
245β
246```ts
247optional validators?: TFormValidators;
248```
249β
250Defined in: [FormApi/FormApi.public.ts:332](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi/FormApi.public.ts#L332)
251β
252An ordered pipeline of form-level validators.
253β
254Validators run for their configured triggers and, by default, during
255submission. Keep the array length stable after initialization so
256validator-indexed errors and schema outputs remain aligned.
257β
258#### Example
259β
260```ts
261validators: [
262 {
263 triggers: ['change'],
264 run: ({ value, createErrorMap }) => {
265 if (value.name) {
266 return null
267 }
268β
269 return createErrorMap({ fields: { name: 'Name is required' } })
270 },
271 },
272],
273```