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

FormOptions.md

273 lines6.2 KB

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
172 // ...
173 onSubmit: async ({ value }) => {
174 await saveUser(value)
175 },
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
209 // ...
210 onSubmitInvalid: () => {
211 document
212 .querySelector<HTMLElement>('[aria-invalid="true"]')
213 ?.focus()
214 },
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```