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

fieldapi.md

568 lines13.9 KB

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:860](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L860)
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:974](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L974)
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:890](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L890)
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:914](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L914)
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:918](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L918)
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:942](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L942)
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:969](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L969)
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:966](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L966)
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:1222](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1222)
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:1190](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1190)
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:1172](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1172)
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:1632](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1632)
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:1625](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1625)
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,
254 opts?): void
255```
256​
257Defined in: [packages/form-core/src/FieldApi.ts:1242](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1242)
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`void`
278​
279***
280​
281### mount()
282​
283```ts
284mount(): () => void
285```
286​
287Defined in: [packages/form-core/src/FieldApi.ts:1067](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1067)
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:1298](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1298)
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:1227](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1227)
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?): void
364```
365​
366Defined in: [packages/form-core/src/FieldApi.ts:1274](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1274)
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`void`
383​
384***
385​
386### replaceValue()
387​
388```ts
389replaceValue(
390 index,
391 value,
392 opts?): void
393```
394​
395Defined in: [packages/form-core/src/FieldApi.ts:1258](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1258)
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`void`
416​
417***
418​
419### setErrorMap()
420​
421```ts
422setErrorMap(errorMap): void
423```
424​
425Defined in: [packages/form-core/src/FieldApi.ts:1652](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1652)
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:1195](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1195)
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:1179](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1179)
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:1286](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1286)
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:1115](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1115)
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:1592](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1592)
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`[]\>