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:859](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L859)
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:973](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L973)
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:889](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L889)
91
92A reference to the form API instance.
93
94***
95
96### name
97
98```ts
99name: unknown extends TParentData ? string : TParentData extends readonly any[] & IsTuple<TParentData> ? PrefixTupleAccessor<TParentData<TParentData>, AllowedIndexes<TParentData<TParentData>, never>, []> : TParentData extends any[] ? PrefixArrayAccessor<TParentData<TParentData>, [any]> : TParentData extends Date ? never : TParentData extends object ? PrefixObjectAccessor<TParentData<TParentData>, []> : TParentData extends string | number | bigint | boolean ? "" : never;
100```
101
102Defined in: [packages/form-core/src/FieldApi.ts:913](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L913)
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:917](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L917)
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:941](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L941)
127
128The field state store.
129
130***
131
132### timeoutIds
133
134```ts
135timeoutIds: Record<ValidationCause, null | Timeout>;
136```
137
138Defined in: [packages/form-core/src/FieldApi.ts:968](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L968)
139
140## Accessors
141
142### state
143
144#### Get Signature
145
146```ts
147get state(): FieldState<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync>
148```
149
150Defined in: [packages/form-core/src/FieldApi.ts:965](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L965)
151
152The current field state.
153
154##### Returns
155
156[`FieldState`](../type-aliases/fieldstate.md)\<`TParentData`, `TName`, `TData`, `TOnMount`, `TOnChange`, `TOnChangeAsync`, `TOnBlur`, `TOnBlurAsync`, `TOnSubmit`, `TOnSubmitAsync`, `TFormOnMount`, `TFormOnChange`, `TFormOnChangeAsync`, `TFormOnBlur`, `TFormOnBlurAsync`, `TFormOnSubmit`, `TFormOnSubmitAsync`\>
157
158## Methods
159
160### getInfo()
161
162```ts
163getInfo(): FieldInfo<TParentData>
164```
165
166Defined in: [packages/form-core/src/FieldApi.ts:1221](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1221)
167
168Gets the field information object.
169
170#### Returns
171
172[`FieldInfo`](../type-aliases/fieldinfo.md)\<`TParentData`\>
173
174***
175
176### getMeta()
177
178```ts
179getMeta(): FieldMeta<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync>
180```
181
182Defined in: [packages/form-core/src/FieldApi.ts:1189](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1189)
183
184#### Returns
185
186[`FieldMeta`](../type-aliases/fieldmeta.md)\<`TParentData`, `TName`, `TData`, `TOnMount`, `TOnChange`, `TOnChangeAsync`, `TOnBlur`, `TOnBlurAsync`, `TOnSubmit`, `TOnSubmitAsync`, `TFormOnMount`, `TFormOnChange`, `TFormOnChangeAsync`, `TFormOnBlur`, `TFormOnBlurAsync`, `TFormOnSubmit`, `TFormOnSubmitAsync`\>
187
188***
189
190### ~~getValue()~~
191
192```ts
193getValue(): TData
194```
195
196Defined in: [packages/form-core/src/FieldApi.ts:1171](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1171)
197
198Gets the current field value.
199
200#### Returns
201
202`TData`
203
204#### Deprecated
205
206Use `field.state.value` instead.
207
208***
209
210### handleBlur()
211
212```ts
213handleBlur(): void
214```
215
216Defined in: [packages/form-core/src/FieldApi.ts:1593](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1593)
217
218Handles the blur event.
219
220#### Returns
221
222`void`
223
224***
225
226### handleChange()
227
228```ts
229handleChange(updater): void
230```
231
232Defined in: [packages/form-core/src/FieldApi.ts:1586](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1586)
233
234Handles the change event.
235
236#### Parameters
237
238##### updater
239
240[`Updater`](../type-aliases/updater.md)\<`TData`\>
241
242#### Returns
243
244`void`
245
246***
247
248### insertValue()
249
250```ts
251insertValue(
252 index,
253 value,
254opts?): Promise<void>
255```
256
257Defined in: [packages/form-core/src/FieldApi.ts:1234](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1234)
258
259Inserts a value at the specified index, shifting the subsequent values to the right.
260
261#### Parameters
262
263##### index
264
265`number`
266
267##### value
268
269`TData` *extends* `any`[] ? `TData`\<`TData`\>\[`number`\] : `never`
270
271##### opts?
272
273`UpdateMetaOptions`
274
275#### Returns
276
277`Promise`\<`void`\>
278
279***
280
281### mount()
282
283```ts
284mount(): () => void
285```
286
287Defined in: [packages/form-core/src/FieldApi.ts:1077](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1077)
288
289Mounts the field instance to the form.
290
291#### Returns
292
293`Function`
294
295##### Returns
296
297`void`
298
299***
300
301### moveValue()
302
303```ts
304moveValue(
305 aIndex,
306 bIndex,
307 opts?): void
308```
309
310Defined in: [packages/form-core/src/FieldApi.ts:1264](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1264)
311
312Moves the value at the first specified index to the second specified index.
313
314#### Parameters
315
316##### aIndex
317
318`number`
319
320##### bIndex
321
322`number`
323
324##### opts?
325
326`UpdateMetaOptions`
327
328#### Returns
329
330`void`
331
332***
333
334### pushValue()
335
336```ts
337pushValue(value, opts?): void
338```
339
340Defined in: [packages/form-core/src/FieldApi.ts:1226](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1226)
341
342Pushes a new value to the field.
343
344#### Parameters
345
346##### value
347
348`TData` *extends* `any`[] ? `TData`\<`TData`\>\[`number`\] : `never`
349
350##### opts?
351
352`UpdateMetaOptions`
353
354#### Returns
355
356`void`
357
358***
359
360### removeValue()
361
362```ts
363removeValue(index, opts?): Promise<void>
364```
365
366Defined in: [packages/form-core/src/FieldApi.ts:1252](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1252)
367
368Removes a value at the specified index.
369
370#### Parameters
371
372##### index
373
374`number`
375
376##### opts?
377
378`UpdateMetaOptions`
379
380#### Returns
381
382`Promise`\<`void`\>
383
384***
385
386### replaceValue()
387
388```ts
389replaceValue(
390 index,
391 value,
392opts?): Promise<void>
393```
394
395Defined in: [packages/form-core/src/FieldApi.ts:1243](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1243)
396
397Replaces a value at the specified index.
398
399#### Parameters
400
401##### index
402
403`number`
404
405##### value
406
407`TData` *extends* `any`[] ? `TData`\<`TData`\>\[`number`\] : `never`
408
409##### opts?
410
411`UpdateMetaOptions`
412
413#### Returns
414
415`Promise`\<`void`\>
416
417***
418
419### setErrorMap()
420
421```ts
422setErrorMap(errorMap): void
423```
424
425Defined in: [packages/form-core/src/FieldApi.ts:1613](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1613)
426
427Updates the field's errorMap
428
429#### Parameters
430
431##### errorMap
432
433`ValidationErrorMap`
434
435#### Returns
436
437`void`
438
439***
440
441### setMeta()
442
443```ts
444setMeta(updater): void
445```
446
447Defined in: [packages/form-core/src/FieldApi.ts:1194](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1194)
448
449Sets the field metadata.
450
451#### Parameters
452
453##### updater
454
455[`Updater`](../type-aliases/updater.md)\<[`FieldMeta`](../type-aliases/fieldmeta.md)\<`TParentData`, `TName`, `TData`, `TOnMount`, `TOnChange`, `TOnChangeAsync`, `TOnBlur`, `TOnBlurAsync`, `TOnSubmit`, `TOnSubmitAsync`, `TFormOnMount`, `TFormOnChange`, `TFormOnChangeAsync`, `TFormOnBlur`, `TFormOnBlurAsync`, `TFormOnSubmit`, `TFormOnSubmitAsync`\>\>
456
457#### Returns
458
459`void`
460
461***
462
463### setValue()
464
465```ts
466setValue(updater, options?): void
467```
468
469Defined in: [packages/form-core/src/FieldApi.ts:1178](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1178)
470
471Sets the field value and run the `change` validator.
472
473#### Parameters
474
475##### updater
476
477[`Updater`](../type-aliases/updater.md)\<`TData`\>
478
479##### options?
480
481`UpdateMetaOptions`
482
483#### Returns
484
485`void`
486
487***
488
489### swapValues()
490
491```ts
492swapValues(
493 aIndex,
494 bIndex,
495 opts?): void
496```
497
498Defined in: [packages/form-core/src/FieldApi.ts:1258](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1258)
499
500Swaps the values at the specified indices.
501
502#### Parameters
503
504##### aIndex
505
506`number`
507
508##### bIndex
509
510`number`
511
512##### opts?
513
514`UpdateMetaOptions`
515
516#### Returns
517
518`void`
519
520***
521
522### update()
523
524```ts
525update(opts): void
526```
527
528Defined in: [packages/form-core/src/FieldApi.ts:1119](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1119)
529
530Updates the field instance with new options.
531
532#### Parameters
533
534##### opts
535
536[`FieldApiOptions`](../interfaces/fieldapioptions.md)\<`TParentData`, `TName`, `TData`, `TOnMount`, `TOnChange`, `TOnChangeAsync`, `TOnBlur`, `TOnBlurAsync`, `TOnSubmit`, `TOnSubmitAsync`, `TFormOnMount`, `TFormOnChange`, `TFormOnChangeAsync`, `TFormOnBlur`, `TFormOnBlurAsync`, `TFormOnSubmit`, `TFormOnSubmitAsync`, `TFormOnServer`, `TParentSubmitMeta`\>
537
538#### Returns
539
540`void`
541
542***
543
544### validate()
545
546```ts
547validate(cause, opts?): unknown[] | Promise<unknown[]>
548```
549
550Defined in: [packages/form-core/src/FieldApi.ts:1553](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1553)
551
552Validates the field value.
553
554#### Parameters
555
556##### cause
557
558`ValidationCause`
559
560##### opts?
561
562###### skipFormValidation?
563
564`boolean`
565
566#### Returns
567
568`unknown`[] \| `Promise`\<`unknown`[]\>