Open History to see the last commit
1---
2id: FieldApi
3title: FieldApi
4---
5
6# Class: FieldApi\<TParentData, TName, TFieldValidator, TFormValidator, TData\>
7
8A class representing the API for managing a form field.
9
10Normally, you will not need to create a new `FieldApi` instance directly.
11Instead, you will use a framework hook/function like `useField` or `createField`
12to create a new instance for you that uses your framework's reactivity model.
13However, if you need to create a new instance manually, you can do so by calling
14the `new FieldApi` constructor.
15
16## Type Parameters
17
18• **TParentData**
19
20• **TName** *extends* [`DeepKeys`](../type-aliases/deepkeys.md)\<`TParentData`\>
21
22• **TFieldValidator** *extends* `Validator`\<[`DeepValue`](../type-aliases/deepvalue.md)\<`TParentData`, `TName`\>, `unknown`\> \| `undefined` = `undefined`
23
24• **TFormValidator** *extends* `Validator`\<`TParentData`, `unknown`\> \| `undefined` = `undefined`
25
26• **TData** *extends* [`DeepValue`](../type-aliases/deepvalue.md)\<`TParentData`, `TName`\> = [`DeepValue`](../type-aliases/deepvalue.md)\<`TParentData`, `TName`\>
27
28## Constructors
29
30### new FieldApi()
31
32```ts
33new FieldApi<TParentData, TName, TFieldValidator, TFormValidator, TData>(opts): FieldApi<TParentData, TName, TFieldValidator, TFormValidator, TData>
34```
35
36Initializes a new `FieldApi` instance.
37
38#### Parameters
39
40• **opts**: [`FieldApiOptions`](../interfaces/fieldapioptions.md)\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\>
41
42#### Returns
43
44[`FieldApi`](fieldapi.md)\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\>
45
46#### Defined in
47
48[packages/form-core/src/FieldApi.ts:440](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L440)
49
50## Properties
51
52### form
53
54```ts
55form: FormApi<TParentData, TFormValidator>;
56```
57
58A reference to the form API instance.
59
60#### Defined in
61
62[packages/form-core/src/FieldApi.ts:402](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L402)
63
64***
65
66### name
67
68```ts
69name: 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;
70```
71
72The field name.
73
74#### Defined in
75
76[packages/form-core/src/FieldApi.ts:412](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L412)
77
78***
79
80### options
81
82```ts
83options: FieldApiOptions<TParentData, TName, TFieldValidator, TFormValidator, TData>;
84```
85
86The field options.
87
88#### Defined in
89
90[packages/form-core/src/FieldApi.ts:416](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L416)
91
92***
93
94### state
95
96```ts
97state: FieldState<TData>;
98```
99
100The current field state.
101
102#### Defined in
103
104[packages/form-core/src/FieldApi.ts:430](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L430)
105
106***
107
108### store
109
110```ts
111store: Store<FieldState<TData>, (cb) => FieldState<TData>>;
112```
113
114The field state store.
115
116#### Defined in
117
118[packages/form-core/src/FieldApi.ts:426](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L426)
119
120***
121
122### timeoutIds
123
124```ts
125timeoutIds: Record<ValidationCause, null | Timeout>;
126```
127
128#### Defined in
129
130[packages/form-core/src/FieldApi.ts:435](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L435)
131
132## Methods
133
134### getInfo()
135
136```ts
137getInfo(): FieldInfo<TParentData, TFormValidator>
138```
139
140Gets the field information object.
141
142#### Returns
143
144[`FieldInfo`](../type-aliases/fieldinfo.md)\<`TParentData`, `TFormValidator`\>
145
146#### Defined in
147
148[packages/form-core/src/FieldApi.ts:658](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L658)
149
150***
151
152### getMeta()
153
154```ts
155getMeta(): FieldMeta
156```
157
158Gets the current field metadata.
159
160#### Returns
161
162[`FieldMeta`](../type-aliases/fieldmeta.md)
163
164#### Defined in
165
166[packages/form-core/src/FieldApi.ts:636](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L636)
167
168***
169
170### ~~getValue()~~
171
172```ts
173getValue(): TData
174```
175
176Gets the current field value.
177
178#### Returns
179
180`TData`
181
182#### Deprecated
183
184Use `field.state.value` instead.
185
186#### Defined in
187
188[packages/form-core/src/FieldApi.ts:616](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L616)
189
190***
191
192### handleBlur()
193
194```ts
195handleBlur(): void
196```
197
198Handles the blur event.
199
200#### Returns
201
202`void`
203
204#### Defined in
205
206[packages/form-core/src/FieldApi.ts:1021](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1021)
207
208***
209
210### handleChange()
211
212```ts
213handleChange(updater): void
214```
215
216Handles the change event.
217
218#### Parameters
219
220• **updater**: [`Updater`](../type-aliases/updater.md)\<`TData`\>
221
222#### Returns
223
224`void`
225
226#### Defined in
227
228[packages/form-core/src/FieldApi.ts:1014](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1014)
229
230***
231
232### insertValue()
233
234```ts
235insertValue(
236 index,
237 value,
238opts?): Promise<void>
239```
240
241Inserts a value at the specified index, shifting the subsequent values to the right.
242
243#### Parameters
244
245• **index**: `number`
246
247• **value**: `TData` *extends* `any`[] ? `TData`\<`TData`\>\[`number`\] : `never`
248
249• **opts?**: `UpdateMetaOptions`
250
251#### Returns
252
253`Promise`\<`void`\>
254
255#### Defined in
256
257[packages/form-core/src/FieldApi.ts:671](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L671)
258
259***
260
261### mount()
262
263```ts
264mount(): () => void
265```
266
267Mounts the field instance to the form.
268
269#### Returns
270
271`Function`
272
273##### Returns
274
275`void`
276
277#### Defined in
278
279[packages/form-core/src/FieldApi.ts:531](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L531)
280
281***
282
283### moveValue()
284
285```ts
286moveValue(
287 aIndex,
288 bIndex,
289 opts?): void
290```
291
292Moves the value at the first specified index to the second specified index.
293
294#### Parameters
295
296• **aIndex**: `number`
297
298• **bIndex**: `number`
299
300• **opts?**: `UpdateMetaOptions`
301
302#### Returns
303
304`void`
305
306#### Defined in
307
308[packages/form-core/src/FieldApi.ts:701](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L701)
309
310***
311
312### pushValue()
313
314```ts
315pushValue(value, opts?): void
316```
317
318Pushes a new value to the field.
319
320#### Parameters
321
322• **value**: `TData` *extends* `any`[] ? `TData`\<`TData`\>\[`number`\] : `never`
323
324• **opts?**: `UpdateMetaOptions`
325
326#### Returns
327
328`void`
329
330#### Defined in
331
332[packages/form-core/src/FieldApi.ts:663](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L663)
333
334***
335
336### removeValue()
337
338```ts
339removeValue(index, opts?): Promise<void>
340```
341
342Removes a value at the specified index.
343
344#### Parameters
345
346• **index**: `number`
347
348• **opts?**: `UpdateMetaOptions`
349
350#### Returns
351
352`Promise`\<`void`\>
353
354#### Defined in
355
356[packages/form-core/src/FieldApi.ts:689](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L689)
357
358***
359
360### replaceValue()
361
362```ts
363replaceValue(
364 index,
365 value,
366opts?): Promise<void>
367```
368
369Replaces a value at the specified index.
370
371#### Parameters
372
373• **index**: `number`
374
375• **value**: `TData` *extends* `any`[] ? `TData`\<`TData`\>\[`number`\] : `never`
376
377• **opts?**: `UpdateMetaOptions`
378
379#### Returns
380
381`Promise`\<`void`\>
382
383#### Defined in
384
385[packages/form-core/src/FieldApi.ts:680](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L680)
386
387***
388
389### setErrorMap()
390
391```ts
392setErrorMap(errorMap): void
393```
394
395Updates the field's errorMap
396
397#### Parameters
398
399• **errorMap**: `ValidationErrorMap`
400
401#### Returns
402
403`void`
404
405#### Defined in
406
407[packages/form-core/src/FieldApi.ts:1036](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1036)
408
409***
410
411### setMeta()
412
413```ts
414setMeta(updater): void
415```
416
417Sets the field metadata.
418
419#### Parameters
420
421• **updater**: [`Updater`](../type-aliases/updater.md)\<[`FieldMeta`](../type-aliases/fieldmeta.md)\>
422
423#### Returns
424
425`void`
426
427#### Defined in
428
429[packages/form-core/src/FieldApi.ts:652](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L652)
430
431***
432
433### setValue()
434
435```ts
436setValue(updater, options?): void
437```
438
439Sets the field value and run the `change` validator.
440
441#### Parameters
442
443• **updater**: [`Updater`](../type-aliases/updater.md)\<`TData`\>
444
445• **options?**: `UpdateMetaOptions`
446
447#### Returns
448
449`void`
450
451#### Defined in
452
453[packages/form-core/src/FieldApi.ts:623](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L623)
454
455***
456
457### swapValues()
458
459```ts
460swapValues(
461 aIndex,
462 bIndex,
463 opts?): void
464```
465
466Swaps the values at the specified indices.
467
468#### Parameters
469
470• **aIndex**: `number`
471
472• **bIndex**: `number`
473
474• **opts?**: `UpdateMetaOptions`
475
476#### Returns
477
478`void`
479
480#### Defined in
481
482[packages/form-core/src/FieldApi.ts:695](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L695)
483
484***
485
486### update()
487
488```ts
489update(opts): void
490```
491
492Updates the field instance with new options.
493
494#### Parameters
495
496• **opts**: [`FieldApiOptions`](../interfaces/fieldapioptions.md)\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\>
497
498#### Returns
499
500`void`
501
502#### Defined in
503
504[packages/form-core/src/FieldApi.ts:579](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L579)
505
506***
507
508### validate()
509
510```ts
511validate(cause): ValidationError[] | Promise<ValidationError[]>
512```
513
514Validates the field value.
515
516#### Parameters
517
518• **cause**: `ValidationCause`
519
520#### Returns
521
522[`ValidationError`](../type-aliases/validationerror.md)[] \| `Promise`\<[`ValidationError`](../type-aliases/validationerror.md)[]\>
523
524#### Defined in
525
526[packages/form-core/src/FieldApi.ts:975](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L975)