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

FormOptionsApi.md

235 lines6.0 KB

1---
2id: FormOptionsApi
3title: FormOptionsApi
4---
5​
6Defined in: [utils.public.ts:205](https://github.com/TanStack/form/blob/main/packages/form-core/src/utils.public.ts#L205)
7​
8The callable API exposed by `formOptions`, including its schema-driven
9inference modes.
10​
11Use `formOptions` directly instead of naming this interface in application
12code.
13​
14## Type Parameters
15​
16### TComponents
17​
18`TComponents`
19​
20Library-managed. Do not specify explicitly.
21​
22```ts
23FormOptionsApi<TFormData, TFormValidators, TSubmitReturn>(options): FormOptions<TFormData, TFormValidators, TSubmitReturn, TComponents>;
24```
25​
26Defined in: [utils.public.ts:226](https://github.com/TanStack/form/blob/main/packages/form-core/src/utils.public.ts#L226)
27​
28Keeps types inferred from `defaultValues`, validators, and submission
29callbacks when form options are declared separately.
30​
31`defaultValues` determine the form data shape in this mode. At runtime,
32this returns the original options object and does not create a form or run
33validation.
34​
35## Type Parameters
36​
37### TFormData
38​
39`TFormData`
40​
41Library-managed. Do not specify explicitly.
42​
43### TFormValidators
44​
45`TFormValidators` *extends* [`FormValidators`](../type-aliases/FormValidators.md)\<`TFormData`\>
46​
47Library-managed. Do not specify explicitly.
48​
49### TSubmitReturn
50​
51`TSubmitReturn`
52​
53Library-managed. Do not specify explicitly.
54​
55## Parameters
56​
57### options
58​
59[`FormOptions`](FormOptions.md)\<`TFormData`, `TFormValidators`, `TSubmitReturn`, `unknown`\>
60​
61## Returns
62​
63[`FormOptions`](FormOptions.md)\<`TFormData`, `TFormValidators`, `TSubmitReturn`, `TComponents`\>
64​
65The original options object, normalized to `FormOptions` with its
66inferred form data, validator, and submission types.
67​
68## Remarks
69​
70**Important:** Although this returns the original object unchanged at
71runtime, its type is normalized to `FormOptions`. Optional properties such
72as `validators` therefore remain optional even when supplied. This
73tradeoff enables safer inference and reuse.
74​
75## Properties
76​
77### looseSchema
78​
79```ts
80looseSchema: FormOptionsLooseSchemaFn<TComponents>;
81```
82​
83Defined in: [utils.public.ts:332](https://github.com/TanStack/form/blob/main/packages/form-core/src/utils.public.ts#L332)
84​
85Infers the form data shape from a Standard Schema validator while allowing
86editable defaults to omit properties or contain `null` or `undefined`
87values.
88​
89Use this when the schema represents the final valid shape but the UI needs
90intermediate empty states, such as an unselected date. Raw form state
91remains available as `value`; read each validator's parsed output from the
92corresponding `validatorOutputs` entry during submission.
93​
94Pass the schema as the first argument and the options as the second.
95`defaultValues` infer an editable form shape constrained by the schema
96input, and callbacks receive that shape merged with the schema input. The
97first argument is ignored at runtime; include the schema in `validators`
98when it should run.
99​
100#### Remarks
101​
102**Important:** Although this returns the original object unchanged at
103runtime, its type is normalized to `FormOptions`. Optional properties such
104as `validators` therefore remain optional even when supplied. This
105tradeoff enables safer inference and reuse.
106​
107#### Example
108​
109```ts
110const bookingSchema = z.object({ startDate: z.date() })
111const bookingOptions = formOptions.looseSchema(bookingSchema, {
112 defaultValues: { startDate: null },
113 validators: [
114 {
115 triggers: ['blur'],
116 run: bookingSchema,
117 },
118 {
119 triggers: ['change'],
120 run: ({ value }) =>
121 value.startDate === null ? 'Choose a date' : undefined,
122 },
123 ],
124 onSubmit: ({ validatorOutputs }) => saveBooking(validatorOutputs[0]),
125})
126```
127​
128#### Returns
129​
130The original options object, normalized to `FormOptions` with
131omitted, nullable, and undefined editable states merged into the schema's
132input shape.
133​
134#### Type Param
135​
136**TSchema**
137​
138Library-managed. Do not specify explicitly.
139​
140#### Type Param
141​
142**TFormValidators**
143​
144Library-managed. Do not specify explicitly.
145​
146#### Type Param
147​
148**TFormData**
149​
150Library-managed. Do not specify explicitly.
151​
152#### Type Param
153​
154**TSubmitReturn**
155​
156Library-managed. Do not specify explicitly.
157​
158***
159​
160### strictSchema
161​
162```ts
163strictSchema: FormOptionsStrictSchemaFn<TComponents>;
164```
165​
166Defined in: [utils.public.ts:280](https://github.com/TanStack/form/blob/main/packages/form-core/src/utils.public.ts#L280)
167​
168Infers the form data type from a Standard Schema validator and requires
169`defaultValues` to match the schema input.
170​
171Use this when the schema represents an input-to-output pipeline. Raw form
172state remains available as `value`; read each validator's parsed output
173from the corresponding `validatorOutputs` entry during submission.
174​
175Pass the schema as the first argument and the options as the second. This
176fixes the form data to the schema input before the options are inferred, so
177each callback receives a typed `value`. The first argument is ignored at
178runtime; include the schema in `validators` when it should run.
179​
180#### Remarks
181​
182**Important:** Although this returns the original object unchanged at
183runtime, its type is normalized to `FormOptions`. Optional properties such
184as `validators` therefore remain optional even when supplied. This
185tradeoff enables safer inference and reuse.
186​
187#### Example
188​
189```ts
190const profileSchema = z.object({ name: z.string().min(1) })
191const profileOptions = formOptions.strictSchema(profileSchema, {
192 defaultValues: { name: '' },
193 validators: [
194 {
195 triggers: ['change'],
196 run: profileSchema,
197 },
198 {
199 triggers: ['change'],
200 run: ({ value }) =>
201 value.name.length === 0 ? 'Name is required' : undefined,
202 },
203 ],
204 onSubmit: ({ validatorOutputs }) => saveProfile(validatorOutputs[0]),
205})
206```
207​
208#### Returns
209​
210The original options object, normalized to `FormOptions` with the
211schema's input shape.
212​
213#### Type Param
214​
215**TSchema**
216​
217Library-managed. Do not specify explicitly.
218​
219#### Type Param
220​
221**TFormValidators**
222​
223Library-managed. Do not specify explicitly.
224​
225#### Type Param
226​
227**TFormData**
228​
229Library-managed. Do not specify explicitly.
230​
231#### Type Param
232​
233**TSubmitReturn**
234​
235Library-managed. Do not specify explicitly.