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`](DeepKeys.md)\<`TParentData`\>
21
22• **TFieldValidator** *extends* `Validator`\<[`DeepValue`](DeepValue.md)\<`TParentData`, `TName`\>, `unknown`\> \| `undefined` = `undefined`
23
24• **TFormValidator** *extends* `Validator`\<`TParentData`, `unknown`\> \| `undefined` = `undefined`
25
26• **TData** *extends* [`DeepValue`](DeepValue.md)\<`TParentData`, `TName`\> = [`DeepValue`](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`](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:432](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L432)
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:395](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L395)
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:405](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L405)
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:409](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L409)
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:423](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L423)
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:419](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L419)
119
120## Methods
121
122### getInfo()
123
124```ts
125getInfo(): FieldInfo<TParentData, TFormValidator>
126```
127
128Gets the field information object.
129
130#### Returns
131
132[`FieldInfo`](FieldInfo.md)\<`TParentData`, `TFormValidator`\>
133
134#### Defined in
135
136[packages/form-core/src/FieldApi.ts:642](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L642)
137
138***
139
140### getMeta()
141
142```ts
143getMeta(): FieldMeta
144```
145
146Gets the current field metadata.
147
148#### Returns
149
150[`FieldMeta`](FieldMeta.md)
151
152#### Defined in
153
154[packages/form-core/src/FieldApi.ts:621](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L621)
155
156***
157
158### ~~getValue()~~
159
160```ts
161getValue(): TData
162```
163
164Gets the current field value.
165
166#### Returns
167
168`TData`
169
170#### Deprecated
171
172Use `field.state.value` instead.
173
174#### Defined in
175
176[packages/form-core/src/FieldApi.ts:601](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L601)
177
178***
179
180### handleBlur()
181
182```ts
183handleBlur(): void
184```
185
186Handles the blur event.
187
188#### Returns
189
190`void`
191
192#### Defined in
193
194[packages/form-core/src/FieldApi.ts:956](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L956)
195
196***
197
198### handleChange()
199
200```ts
201handleChange(updater): void
202```
203
204Handles the change event.
205
206#### Parameters
207
208• **updater**: [`Updater`](Updater.md)\<`TData`\>
209
210#### Returns
211
212`void`
213
214#### Defined in
215
216[packages/form-core/src/FieldApi.ts:949](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L949)
217
218***
219
220### insertValue()
221
222```ts
223insertValue(
224 index,
225 value,
226opts?): Promise<void>
227```
228
229Inserts a value at the specified index, shifting the subsequent values to the right.
230
231#### Parameters
232
233• **index**: `number`
234
235• **value**: `TData` *extends* `any`[] ? `TData`\<`TData`\>\[`number`\] : `never`
236
237• **opts?**: `UpdateMetaOptions`
238
239#### Returns
240
241`Promise`\<`void`\>
242
243#### Defined in
244
245[packages/form-core/src/FieldApi.ts:655](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L655)
246
247***
248
249### mount()
250
251```ts
252mount(): () => void
253```
254
255Mounts the field instance to the form.
256
257#### Returns
258
259`Function`
260
261##### Returns
262
263`void`
264
265#### Defined in
266
267[packages/form-core/src/FieldApi.ts:517](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L517)
268
269***
270
271### moveValue()
272
273```ts
274moveValue(
275 aIndex,
276 bIndex,
277 opts?): void
278```
279
280Moves the value at the first specified index to the second specified index.
281
282#### Parameters
283
284• **aIndex**: `number`
285
286• **bIndex**: `number`
287
288• **opts?**: `UpdateMetaOptions`
289
290#### Returns
291
292`void`
293
294#### Defined in
295
296[packages/form-core/src/FieldApi.ts:685](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L685)
297
298***
299
300### pushValue()
301
302```ts
303pushValue(value, opts?): void
304```
305
306Pushes a new value to the field.
307
308#### Parameters
309
310• **value**: `TData` *extends* `any`[] ? `TData`\<`TData`\>\[`number`\] : `never`
311
312• **opts?**: `UpdateMetaOptions`
313
314#### Returns
315
316`void`
317
318#### Defined in
319
320[packages/form-core/src/FieldApi.ts:647](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L647)
321
322***
323
324### removeValue()
325
326```ts
327removeValue(index, opts?): Promise<void>
328```
329
330Removes a value at the specified index.
331
332#### Parameters
333
334• **index**: `number`
335
336• **opts?**: `UpdateMetaOptions`
337
338#### Returns
339
340`Promise`\<`void`\>
341
342#### Defined in
343
344[packages/form-core/src/FieldApi.ts:673](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L673)
345
346***
347
348### replaceValue()
349
350```ts
351replaceValue(
352 index,
353 value,
354opts?): Promise<void>
355```
356
357Replaces a value at the specified index.
358
359#### Parameters
360
361• **index**: `number`
362
363• **value**: `TData` *extends* `any`[] ? `TData`\<`TData`\>\[`number`\] : `never`
364
365• **opts?**: `UpdateMetaOptions`
366
367#### Returns
368
369`Promise`\<`void`\>
370
371#### Defined in
372
373[packages/form-core/src/FieldApi.ts:664](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L664)
374
375***
376
377### setMeta()
378
379```ts
380setMeta(updater): void
381```
382
383Sets the field metadata.
384
385#### Parameters
386
387• **updater**: [`Updater`](Updater.md)\<[`FieldMeta`](FieldMeta.md)\>
388
389#### Returns
390
391`void`
392
393#### Defined in
394
395[packages/form-core/src/FieldApi.ts:636](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L636)
396
397***
398
399### setValue()
400
401```ts
402setValue(updater, options?): void
403```
404
405Sets the field value and run the `change` validator.
406
407#### Parameters
408
409• **updater**: [`Updater`](Updater.md)\<`TData`\>
410
411• **options?**: `UpdateMetaOptions`
412
413#### Returns
414
415`void`
416
417#### Defined in
418
419[packages/form-core/src/FieldApi.ts:608](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L608)
420
421***
422
423### swapValues()
424
425```ts
426swapValues(
427 aIndex,
428 bIndex,
429 opts?): void
430```
431
432Swaps the values at the specified indices.
433
434#### Parameters
435
436• **aIndex**: `number`
437
438• **bIndex**: `number`
439
440• **opts?**: `UpdateMetaOptions`
441
442#### Returns
443
444`void`
445
446#### Defined in
447
448[packages/form-core/src/FieldApi.ts:679](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L679)
449
450***
451
452### update()
453
454```ts
455update(opts): void
456```
457
458Updates the field instance with new options.
459
460#### Parameters
461
462• **opts**: [`FieldApiOptions`](FieldApiOptions.md)\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\>
463
464#### Returns
465
466`void`
467
468#### Defined in
469
470[packages/form-core/src/FieldApi.ts:564](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L564)
471
472***
473
474### validate()
475
476```ts
477validate(cause): ValidationError[] | Promise<ValidationError[]>
478```
479
480Validates the field value.
481
482#### Parameters
483
484• **cause**: `ValidationCause`
485
486#### Returns
487
488[`ValidationError`](ValidationError.md)[] \| `Promise`\<[`ValidationError`](ValidationError.md)[]\>
489
490#### Defined in
491
492[packages/form-core/src/FieldApi.ts:923](https://github.com/TanStack/form/blob/a6313b7699753752ae30ff16c169e0b08c2369e8/packages/form-core/src/FieldApi.ts#L923)