Open History to see the last commit
1---
2id: FieldApi
3title: FieldApi
4---
5
6<!-- DO NOT EDIT: this page is autogenerated from the type comments -->
7
8# Class: FieldApi\<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnServer, TParentSubmitMeta\>
9
10Defined in: [packages/form-core/src/FieldApi.ts:863](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L863)
11
12A class representing the API for managing a form field.
13
14Normally, you will not need to create a new `FieldApi` instance directly.
15Instead, you will use a framework hook/function like `useField` or `createField`
16to create a new instance for you that uses your framework's reactivity model.
17However, if you need to create a new instance manually, you can do so by calling
18the `new FieldApi` constructor.
19
20## Type Parameters
21
22• **TParentData**
23
24• **TName** *extends* [`DeepKeys`](../../type-aliases/deepkeys.md)\<`TParentData`\>
25
26• **TData** *extends* [`DeepValue`](../../type-aliases/deepvalue.md)\<`TParentData`, `TName`\>
27
28• **TOnMount** *extends* `undefined` \| `FieldValidateOrFn`\<`TParentData`, `TName`, `TData`\>
29
30• **TOnChange** *extends* `undefined` \| `FieldValidateOrFn`\<`TParentData`, `TName`, `TData`\>
31
32• **TOnChangeAsync** *extends* `undefined` \| `FieldAsyncValidateOrFn`\<`TParentData`, `TName`, `TData`\>
33
34• **TOnBlur** *extends* `undefined` \| `FieldValidateOrFn`\<`TParentData`, `TName`, `TData`\>
35
36• **TOnBlurAsync** *extends* `undefined` \| `FieldAsyncValidateOrFn`\<`TParentData`, `TName`, `TData`\>
37
38• **TOnSubmit** *extends* `undefined` \| `FieldValidateOrFn`\<`TParentData`, `TName`, `TData`\>
39
40• **TOnSubmitAsync** *extends* `undefined` \| `FieldAsyncValidateOrFn`\<`TParentData`, `TName`, `TData`\>
41
42• **TFormOnMount** *extends* `undefined` \| `FormValidateOrFn`\<`TParentData`\>
43
44• **TFormOnChange** *extends* `undefined` \| `FormValidateOrFn`\<`TParentData`\>
45
46• **TFormOnChangeAsync** *extends* `undefined` \| `FormAsyncValidateOrFn`\<`TParentData`\>
47
48• **TFormOnBlur** *extends* `undefined` \| `FormValidateOrFn`\<`TParentData`\>
49
50• **TFormOnBlurAsync** *extends* `undefined` \| `FormAsyncValidateOrFn`\<`TParentData`\>
51
52• **TFormOnSubmit** *extends* `undefined` \| `FormValidateOrFn`\<`TParentData`\>
53
54• **TFormOnSubmitAsync** *extends* `undefined` \| `FormAsyncValidateOrFn`\<`TParentData`\>
55
56• **TFormOnServer** *extends* `undefined` \| `FormAsyncValidateOrFn`\<`TParentData`\>
57
58• **TParentSubmitMeta**
59
60## Constructors
61
62### new FieldApi()
63
64```ts
65new FieldApi<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnServer, TParentSubmitMeta>(opts): FieldApi<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnServer, TParentSubmitMeta>
66```
67
68Defined in: [packages/form-core/src/FieldApi.ts:995](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L995)
69
70Initializes a new `FieldApi` instance.
71
72#### Parameters
73
74##### opts
75
76[`FieldApiOptions`](../../interfaces/fieldapioptions.md)\<`TParentData`, `TName`, `TData`, `TOnMount`, `TOnChange`, `TOnChangeAsync`, `TOnBlur`, `TOnBlurAsync`, `TOnSubmit`, `TOnSubmitAsync`, `TFormOnMount`, `TFormOnChange`, `TFormOnChangeAsync`, `TFormOnBlur`, `TFormOnBlurAsync`, `TFormOnSubmit`, `TFormOnSubmitAsync`, `TFormOnServer`, `TParentSubmitMeta`\>
77
78#### Returns
79
80[`FieldApi`](../fieldapi.md)\<`TParentData`, `TName`, `TData`, `TOnMount`, `TOnChange`, `TOnChangeAsync`, `TOnBlur`, `TOnBlurAsync`, `TOnSubmit`, `TOnSubmitAsync`, `TFormOnMount`, `TFormOnChange`, `TFormOnChangeAsync`, `TFormOnBlur`, `TFormOnBlurAsync`, `TFormOnSubmit`, `TFormOnSubmitAsync`, `TFormOnServer`, `TParentSubmitMeta`\>
81
82## Properties
83
84### form
85
86```ts
87form: FormApi<TParentData, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnServer, TParentSubmitMeta>;
88```
89
90Defined in: [packages/form-core/src/FieldApi.ts:907](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L907)
91
92A reference to the form API instance.
93
94***
95
96### name
97
98```ts
99name: DeepKeys<TParentData>;
100```
101
102Defined in: [packages/form-core/src/FieldApi.ts:931](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L931)
103
104The field name.
105
106***
107
108### options
109
110```ts
111options: FieldApiOptions<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnServer, TParentSubmitMeta>;
112```
113
114Defined in: [packages/form-core/src/FieldApi.ts:935](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L935)
115
116The field options.
117
118***
119
120### store
121
122```ts
123store: Derived<FieldState<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync>>;
124```
125
126Defined in: [packages/form-core/src/FieldApi.ts:959](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L959)
127
128The field state store.
129
130***
131
132### timeoutIds
133
134```ts
135timeoutIds: object;
136```
137
138Defined in: [packages/form-core/src/FieldApi.ts:986](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L986)
139
140#### formListeners
141
142```ts
143formListeners: Record<ListenerCause, null | Timeout>;
144```
145
146#### listeners
147
148```ts
149listeners: Record<ListenerCause, null | Timeout>;
150```
151
152#### validations
153
154```ts
155validations: Record<ValidationCause, null | Timeout>;
156```
157
158## Accessors
159
160### state
161
162#### Get Signature
163
164```ts
165get state(): FieldState<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync>
166```
167
168Defined in: [packages/form-core/src/FieldApi.ts:983](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L983)
169
170The current field state.
171
172##### Returns
173
174[`FieldState`](../../type-aliases/fieldstate.md)\<`TParentData`, `TName`, `TData`, `TOnMount`, `TOnChange`, `TOnChangeAsync`, `TOnBlur`, `TOnBlurAsync`, `TOnSubmit`, `TOnSubmitAsync`, `TFormOnMount`, `TFormOnChange`, `TFormOnChangeAsync`, `TFormOnBlur`, `TFormOnBlurAsync`, `TFormOnSubmit`, `TFormOnSubmitAsync`\>
175
176## Methods
177
178### getInfo()
179
180```ts
181getInfo(): FieldInfo<TParentData>
182```
183
184Defined in: [packages/form-core/src/FieldApi.ts:1249](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1249)
185
186Gets the field information object.
187
188#### Returns
189
190[`FieldInfo`](../../type-aliases/fieldinfo.md)\<`TParentData`\>
191
192***
193
194### getMeta()
195
196```ts
197getMeta(): FieldMeta<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync>
198```
199
200Defined in: [packages/form-core/src/FieldApi.ts:1217](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1217)
201
202#### Returns
203
204[`FieldMeta`](../../type-aliases/fieldmeta.md)\<`TParentData`, `TName`, `TData`, `TOnMount`, `TOnChange`, `TOnChangeAsync`, `TOnBlur`, `TOnBlurAsync`, `TOnSubmit`, `TOnSubmitAsync`, `TFormOnMount`, `TFormOnChange`, `TFormOnChangeAsync`, `TFormOnBlur`, `TFormOnBlurAsync`, `TFormOnSubmit`, `TFormOnSubmitAsync`\>
205
206***
207
208### ~~getValue()~~
209
210```ts
211getValue(): TData
212```
213
214Defined in: [packages/form-core/src/FieldApi.ts:1202](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1202)
215
216Gets the current field value.
217
218#### Returns
219
220`TData`
221
222#### Deprecated
223
224Use `field.state.value` instead.
225
226***
227
228### handleBlur()
229
230```ts
231handleBlur(): void
232```
233
234Defined in: [packages/form-core/src/FieldApi.ts:1661](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1661)
235
236Handles the blur event.
237
238#### Returns
239
240`void`
241
242***
243
244### handleChange()
245
246```ts
247handleChange(updater): void
248```
249
250Defined in: [packages/form-core/src/FieldApi.ts:1654](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1654)
251
252Handles the change event.
253
254#### Parameters
255
256##### updater
257
258[`Updater`](../../type-aliases/updater.md)\<`TData`\>
259
260#### Returns
261
262`void`
263
264***
265
266### insertValue()
267
268```ts
269insertValue(
270 index,
271 value,
272 opts?): void
273```
274
275Defined in: [packages/form-core/src/FieldApi.ts:1266](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1266)
276
277Inserts a value at the specified index, shifting the subsequent values to the right.
278
279#### Parameters
280
281##### index
282
283`number`
284
285##### value
286
287`TData` *extends* `any`[] ? `TData`\<`TData`\>\[`number`\] : `never`
288
289##### opts?
290
291`UpdateMetaOptions`
292
293#### Returns
294
295`void`
296
297***
298
299### mount()
300
301```ts
302mount(): () => void
303```
304
305Defined in: [packages/form-core/src/FieldApi.ts:1092](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1092)
306
307Mounts the field instance to the form.
308
309#### Returns
310
311`Function`
312
313##### Returns
314
315`void`
316
317***
318
319### moveValue()
320
321```ts
322moveValue(
323 aIndex,
324 bIndex,
325 opts?): void
326```
327
328Defined in: [packages/form-core/src/FieldApi.ts:1310](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1310)
329
330Moves the value at the first specified index to the second specified index.
331
332#### Parameters
333
334##### aIndex
335
336`number`
337
338##### bIndex
339
340`number`
341
342##### opts?
343
344`UpdateMetaOptions`
345
346#### Returns
347
348`void`
349
350***
351
352### parseValueWithSchema()
353
354```ts
355parseValueWithSchema(schema):
356 | undefined
357 | StandardSchemaV1Issue[]
358```
359
360Defined in: [packages/form-core/src/FieldApi.ts:1703](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1703)
361
362Parses the field's value with the given schema and returns
363issues (if any). This method does NOT set any internal errors.
364
365#### Parameters
366
367##### schema
368
369[`StandardSchemaV1`](../../type-aliases/standardschemav1.md)\<`TData`, `unknown`\>
370
371The standard schema to parse this field's value with.
372
373#### Returns
374
375 \| `undefined`
376 \| [`StandardSchemaV1Issue`](../../interfaces/standardschemav1issue.md)[]
377
378***
379
380### parseValueWithSchemaAsync()
381
382```ts
383parseValueWithSchemaAsync(schema): Promise<
384 | undefined
385| StandardSchemaV1Issue[]>
386```
387
388Defined in: [packages/form-core/src/FieldApi.ts:1715](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1715)
389
390Parses the field's value with the given schema and returns
391issues (if any). This method does NOT set any internal errors.
392
393#### Parameters
394
395##### schema
396
397[`StandardSchemaV1`](../../type-aliases/standardschemav1.md)\<`TData`, `unknown`\>
398
399The standard schema to parse this field's value with.
400
401#### Returns
402
403`Promise`\<
404 \| `undefined`
405 \| [`StandardSchemaV1Issue`](../../interfaces/standardschemav1issue.md)[]\>
406
407***
408
409### pushValue()
410
411```ts
412pushValue(value, opts?): void
413```
414
415Defined in: [packages/form-core/src/FieldApi.ts:1254](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1254)
416
417Pushes a new value to the field.
418
419#### Parameters
420
421##### value
422
423`TData` *extends* `any`[] ? `TData`\<`TData`\>\[`number`\] : `never`
424
425##### opts?
426
427`UpdateMetaOptions`
428
429#### Returns
430
431`void`
432
433***
434
435### removeValue()
436
437```ts
438removeValue(index, opts?): void
439```
440
441Defined in: [packages/form-core/src/FieldApi.ts:1292](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1292)
442
443Removes a value at the specified index.
444
445#### Parameters
446
447##### index
448
449`number`
450
451##### opts?
452
453`UpdateMetaOptions`
454
455#### Returns
456
457`void`
458
459***
460
461### replaceValue()
462
463```ts
464replaceValue(
465 index,
466 value,
467 opts?): void
468```
469
470Defined in: [packages/form-core/src/FieldApi.ts:1279](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1279)
471
472Replaces a value at the specified index.
473
474#### Parameters
475
476##### index
477
478`number`
479
480##### value
481
482`TData` *extends* `any`[] ? `TData`\<`TData`\>\[`number`\] : `never`
483
484##### opts?
485
486`UpdateMetaOptions`
487
488#### Returns
489
490`void`
491
492***
493
494### setErrorMap()
495
496```ts
497setErrorMap(errorMap): void
498```
499
500Defined in: [packages/form-core/src/FieldApi.ts:1678](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1678)
501
502Updates the field's errorMap
503
504#### Parameters
505
506##### errorMap
507
508`ValidationErrorMap`\<[`UnwrapFieldValidateOrFn`](../../type-aliases/unwrapfieldvalidateorfn.md)\<`TName`, `TOnMount`, `TFormOnMount`\>, [`UnwrapFieldValidateOrFn`](../../type-aliases/unwrapfieldvalidateorfn.md)\<`TName`, `TOnChange`, `TFormOnChange`\>, [`UnwrapFieldAsyncValidateOrFn`](../../type-aliases/unwrapfieldasyncvalidateorfn.md)\<`TName`, `TOnChangeAsync`, `TFormOnChangeAsync`\>, [`UnwrapFieldValidateOrFn`](../../type-aliases/unwrapfieldvalidateorfn.md)\<`TName`, `TOnBlur`, `TFormOnBlur`\>, [`UnwrapFieldAsyncValidateOrFn`](../../type-aliases/unwrapfieldasyncvalidateorfn.md)\<`TName`, `TOnBlurAsync`, `TFormOnBlurAsync`\>, [`UnwrapFieldValidateOrFn`](../../type-aliases/unwrapfieldvalidateorfn.md)\<`TName`, `TOnSubmit`, `TFormOnSubmit`\>, [`UnwrapFieldAsyncValidateOrFn`](../../type-aliases/unwrapfieldasyncvalidateorfn.md)\<`TName`, `TOnSubmitAsync`, `TFormOnSubmitAsync`\>\>
509
510#### Returns
511
512`void`
513
514***
515
516### setMeta()
517
518```ts
519setMeta(updater): void
520```
521
522Defined in: [packages/form-core/src/FieldApi.ts:1222](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1222)
523
524Sets the field metadata.
525
526#### Parameters
527
528##### updater
529
530[`Updater`](../../type-aliases/updater.md)\<[`FieldMetaBase`](../../type-aliases/fieldmetabase.md)\<`TParentData`, `TName`, `TData`, `TOnMount`, `TOnChange`, `TOnChangeAsync`, `TOnBlur`, `TOnBlurAsync`, `TOnSubmit`, `TOnSubmitAsync`, `TFormOnMount`, `TFormOnChange`, `TFormOnChangeAsync`, `TFormOnBlur`, `TFormOnBlurAsync`, `TFormOnSubmit`, `TFormOnSubmitAsync`\>\>
531
532#### Returns
533
534`void`
535
536***
537
538### setValue()
539
540```ts
541setValue(updater, options?): void
542```
543
544Defined in: [packages/form-core/src/FieldApi.ts:1209](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1209)
545
546Sets the field value and run the `change` validator.
547
548#### Parameters
549
550##### updater
551
552[`Updater`](../../type-aliases/updater.md)\<`TData`\>
553
554##### options?
555
556`UpdateMetaOptions`
557
558#### Returns
559
560`void`
561
562***
563
564### swapValues()
565
566```ts
567swapValues(
568 aIndex,
569 bIndex,
570 opts?): void
571```
572
573Defined in: [packages/form-core/src/FieldApi.ts:1301](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1301)
574
575Swaps the values at the specified indices.
576
577#### Parameters
578
579##### aIndex
580
581`number`
582
583##### bIndex
584
585`number`
586
587##### opts?
588
589`UpdateMetaOptions`
590
591#### Returns
592
593`void`
594
595***
596
597### update()
598
599```ts
600update(opts): void
601```
602
603Defined in: [packages/form-core/src/FieldApi.ts:1145](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1145)
604
605Updates the field instance with new options.
606
607#### Parameters
608
609##### opts
610
611[`FieldApiOptions`](../../interfaces/fieldapioptions.md)\<`TParentData`, `TName`, `TData`, `TOnMount`, `TOnChange`, `TOnChangeAsync`, `TOnBlur`, `TOnBlurAsync`, `TOnSubmit`, `TOnSubmitAsync`, `TFormOnMount`, `TFormOnChange`, `TFormOnChangeAsync`, `TFormOnBlur`, `TFormOnBlurAsync`, `TFormOnSubmit`, `TFormOnSubmitAsync`, `TFormOnServer`, `TParentSubmitMeta`\>
612
613#### Returns
614
615`void`
616
617***
618
619### validate()
620
621```ts
622validate(cause, opts?): unknown[] | Promise<unknown[]>
623```
624
625Defined in: [packages/form-core/src/FieldApi.ts:1621](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1621)
626
627Validates the field value.
628
629#### Parameters
630
631##### cause
632
633`ValidationCause`
634
635##### opts?
636
637###### skipFormValidation?
638
639`boolean`
640
641#### Returns
642
643`unknown`[] \| `Promise`\<`unknown`[]\>