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

fieldapi.md

643 lines15.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: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`[]\>