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

FieldGroupApi.md

866 lines14.5 KB

1---
2id: FieldGroupApi
3title: FieldGroupApi
4---
5​
6# Class: FieldGroupApi\<TFormData, TFieldGroupData, TFields, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta\>
7​
8Defined in: [packages/form-core/src/FieldGroupApi.ts:114](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldGroupApi.ts#L114)
9​
10## Type Parameters
11​
12### TFormData
13​
14`TFormData`
15​
16### TFieldGroupData
17​
18`TFieldGroupData`
19​
20### TFields
21​
22`TFields` *extends*
23 \| [`DeepKeysOfType`](../type-aliases/DeepKeysOfType.md)\<`TFormData`, `TFieldGroupData` \| `null` \| `undefined`\>
24 \| [`FieldsMap`](../type-aliases/FieldsMap.md)\<`TFormData`, `TFieldGroupData`\>
25​
26### TOnMount
27​
28`TOnMount` *extends* `undefined` \| `FormValidateOrFn`\<`TFormData`\>
29​
30### TOnChange
31​
32`TOnChange` *extends* `undefined` \| `FormValidateOrFn`\<`TFormData`\>
33​
34### TOnChangeAsync
35​
36`TOnChangeAsync` *extends* `undefined` \| `FormAsyncValidateOrFn`\<`TFormData`\>
37​
38### TOnBlur
39​
40`TOnBlur` *extends* `undefined` \| `FormValidateOrFn`\<`TFormData`\>
41​
42### TOnBlurAsync
43​
44`TOnBlurAsync` *extends* `undefined` \| `FormAsyncValidateOrFn`\<`TFormData`\>
45​
46### TOnSubmit
47​
48`TOnSubmit` *extends* `undefined` \| `FormValidateOrFn`\<`TFormData`\>
49​
50### TOnSubmitAsync
51​
52`TOnSubmitAsync` *extends* `undefined` \| `FormAsyncValidateOrFn`\<`TFormData`\>
53​
54### TOnDynamic
55​
56`TOnDynamic` *extends* `undefined` \| `FormValidateOrFn`\<`TFormData`\>
57​
58### TOnDynamicAsync
59​
60`TOnDynamicAsync` *extends* `undefined` \| `FormAsyncValidateOrFn`\<`TFormData`\>
61​
62### TOnServer
63​
64`TOnServer` *extends* `undefined` \| `FormAsyncValidateOrFn`\<`TFormData`\>
65​
66### TSubmitMeta
67​
68`TSubmitMeta` = `never`
69​
70## Constructors
71​
72### Constructor
73​
74```ts
75new FieldGroupApi<TFormData, TFieldGroupData, TFields, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta>(opts): FieldGroupApi<TFormData, TFieldGroupData, TFields, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta>;
76```
77​
78Defined in: [packages/form-core/src/FieldGroupApi.ts:239](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldGroupApi.ts#L239)
79​
80Constructs a new `FieldGroupApi` instance with the given form options.
81​
82#### Parameters
83​
84##### opts
85​
86[`FieldGroupOptions`](../interfaces/FieldGroupOptions.md)\<`TFormData`, `TFieldGroupData`, `TFields`, `TOnMount`, `TOnChange`, `TOnChangeAsync`, `TOnBlur`, `TOnBlurAsync`, `TOnSubmit`, `TOnSubmitAsync`, `TOnDynamic`, `TOnDynamicAsync`, `TOnServer`, `TSubmitMeta`\>
87​
88#### Returns
89​
90`FieldGroupApi`\<`TFormData`, `TFieldGroupData`, `TFields`, `TOnMount`, `TOnChange`, `TOnChangeAsync`, `TOnBlur`, `TOnBlurAsync`, `TOnSubmit`, `TOnSubmitAsync`, `TOnDynamic`, `TOnDynamicAsync`, `TOnServer`, `TSubmitMeta`\>
91​
92## Properties
93​
94### fieldsMap
95​
96```ts
97readonly fieldsMap: TFields;
98```
99​
100Defined in: [packages/form-core/src/FieldGroupApi.ts:150](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldGroupApi.ts#L150)
101​
102***
103​
104### form
105​
106```ts
107readonly form: FormApi<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta>;
108```
109​
110Defined in: [packages/form-core/src/FieldGroupApi.ts:135](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldGroupApi.ts#L135)
111​
112The form that called this field group.
113​
114***
115​
116### store
117​
118```ts
119store: ReadonlyStore<FieldGroupState<TFieldGroupData>>;
120```
121​
122Defined in: [packages/form-core/src/FieldGroupApi.ts:230](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldGroupApi.ts#L230)
123​
124## Accessors
125​
126### state
127​
128#### Get Signature
129​
130```ts
131get state(): FieldGroupState<TFieldGroupData>;
132```
133​
134Defined in: [packages/form-core/src/FieldGroupApi.ts:232](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldGroupApi.ts#L232)
135​
136##### Returns
137​
138[`FieldGroupState`](../interfaces/FieldGroupState.md)\<`TFieldGroupData`\>
139​
140## Methods
141​
142### clearFieldValues()
143​
144```ts
145clearFieldValues<TField>(field, opts?): void;
146```
147​
148Defined in: [packages/form-core/src/FieldGroupApi.ts:508](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldGroupApi.ts#L508)
149​
150#### Type Parameters
151​
152##### TField
153​
154`TField` *extends* `string`
155​
156#### Parameters
157​
158##### field
159​
160`TField`
161​
162##### opts?
163​
164`UpdateMetaOptions`
165​
166#### Returns
167​
168`void`
169​
170#### Implementation of
171​
172```ts
173FormLikeAPI.clearFieldValues
174```
175​
176***
177​
178### deleteField()
179​
180```ts
181deleteField<TField>(field): void;
182```
183​
184Defined in: [packages/form-core/src/FieldGroupApi.ts:395](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldGroupApi.ts#L395)
185​
186Delete a field and its subfields.
187​
188#### Type Parameters
189​
190##### TField
191​
192`TField` *extends* `string`
193​
194#### Parameters
195​
196##### field
197​
198`TField`
199​
200#### Returns
201​
202`void`
203​
204#### Implementation of
205​
206```ts
207FormLikeAPI.deleteField
208```
209​
210***
211​
212### getFieldMeta()
213​
214```ts
215getFieldMeta<TField>(field): AnyFieldLikeMeta | undefined;
216```
217​
218Defined in: [packages/form-core/src/FieldGroupApi.ts:363](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldGroupApi.ts#L363)
219​
220Gets the metadata of the specified field.
221​
222#### Type Parameters
223​
224##### TField
225​
226`TField` *extends* `string`
227​
228#### Parameters
229​
230##### field
231​
232`TField`
233​
234#### Returns
235​
236`AnyFieldLikeMeta` \| `undefined`
237​
238#### Implementation of
239​
240```ts
241FormLikeAPI.getFieldMeta
242```
243​
244***
245​
246### getFieldValue()
247​
248```ts
249getFieldValue<TField>(field): DeepValue<TFieldGroupData, TField>;
250```
251​
252Defined in: [packages/form-core/src/FieldGroupApi.ts:351](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldGroupApi.ts#L351)
253​
254Gets the value of the specified field.
255​
256#### Type Parameters
257​
258##### TField
259​
260`TField` *extends* `string`
261​
262#### Parameters
263​
264##### field
265​
266`TField`
267​
268#### Returns
269​
270[`DeepValue`](../type-aliases/DeepValue.md)\<`TFieldGroupData`, `TField`\>
271​
272#### Implementation of
273​
274```ts
275FormLikeAPI.getFieldValue
276```
277​
278***
279​
280### handleSubmit()
281​
282#### Call Signature
283​
284```ts
285handleSubmit(): Promise<void>;
286```
287​
288Defined in: [packages/form-core/src/FieldGroupApi.ts:341](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldGroupApi.ts#L341)
289​
290Handles the form submission, performs validation, and calls the appropriate onSubmit or onSubmitInvalid callbacks.
291​
292##### Returns
293​
294`Promise`\<`void`\>
295​
296##### Implementation of
297​
298```ts
299FormLikeAPI.handleSubmit
300```
301​
302#### Call Signature
303​
304```ts
305handleSubmit(submitMeta): Promise<void>;
306```
307​
308Defined in: [packages/form-core/src/FieldGroupApi.ts:342](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldGroupApi.ts#L342)
309​
310Handles the form submission, performs validation, and calls the appropriate onSubmit or onSubmitInvalid callbacks.
311​
312##### Parameters
313​
314###### submitMeta
315​
316`TSubmitMeta`
317​
318##### Returns
319​
320`Promise`\<`void`\>
321​
322##### Implementation of
323​
324```ts
325FormLikeAPI.handleSubmit
326```
327​
328***
329​
330### insertFieldValue()
331​
332```ts
333insertFieldValue<TField>(
334 field,
335 index,
336 value,
337opts?): Promise<void>;
338```
339​
340Defined in: [packages/form-core/src/FieldGroupApi.ts:420](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldGroupApi.ts#L420)
341​
342Insert a value into an array field at the specified index.
343​
344#### Type Parameters
345​
346##### TField
347​
348`TField` *extends* `string`
349​
350#### Parameters
351​
352##### field
353​
354`TField`
355​
356##### index
357​
358`number`
359​
360##### value
361​
362[`DeepValue`](../type-aliases/DeepValue.md)\<`TFieldGroupData`, `TField`\> *extends* `any`[] ? `any`[] & [`DeepValue`](../type-aliases/DeepValue.md)\<`TFieldGroupData`, `TField`\>\[`number`\] : `never`
363​
364##### opts?
365​
366`UpdateMetaOptions`
367​
368#### Returns
369​
370`Promise`\<`void`\>
371​
372#### Implementation of
373​
374```ts
375FormLikeAPI.insertFieldValue
376```
377​
378***
379​
380### mount()
381​
382```ts
383mount(): () => void;
384```
385​
386Defined in: [packages/form-core/src/FieldGroupApi.ts:307](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldGroupApi.ts#L307)
387​
388Mounts the field group instance to listen to value changes.
389​
390TODO: Remove
391​
392#### Returns
393​
394```ts
395(): void;
396```
397​
398##### Returns
399​
400`void`
401​
402***
403​
404### moveFieldValues()
405​
406```ts
407moveFieldValues<TField>(
408 field,
409 index1,
410 index2,
411 opts?): void;
412```
413​
414Defined in: [packages/form-core/src/FieldGroupApi.ts:494](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldGroupApi.ts#L494)
415​
416Moves the value at the first specified index to the second specified index within an array field.
417​
418#### Type Parameters
419​
420##### TField
421​
422`TField` *extends* `string`
423​
424#### Parameters
425​
426##### field
427​
428`TField`
429​
430##### index1
431​
432`number`
433​
434##### index2
435​
436`number`
437​
438##### opts?
439​
440`UpdateMetaOptions`
441​
442#### Returns
443​
444`void`
445​
446#### Implementation of
447​
448```ts
449FormLikeAPI.moveFieldValues
450```
451​
452***
453​
454### pushFieldValue()
455​
456```ts
457pushFieldValue<TField>(
458 field,
459 value,
460 opts?): void;
461```
462​
463Defined in: [packages/form-core/src/FieldGroupApi.ts:402](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldGroupApi.ts#L402)
464​
465Pushes a value into an array field.
466​
467#### Type Parameters
468​
469##### TField
470​
471`TField` *extends* `string`
472​
473#### Parameters
474​
475##### field
476​
477`TField`
478​
479##### value
480​
481[`DeepValue`](../type-aliases/DeepValue.md)\<`TFieldGroupData`, `TField`\> *extends* `any`[] ? `any`[] & [`DeepValue`](../type-aliases/DeepValue.md)\<`TFieldGroupData`, `TField`\>\[`number`\] : `never`
482​
483##### opts?
484​
485`UpdateMetaOptions`
486​
487#### Returns
488​
489`void`
490​
491#### Implementation of
492​
493```ts
494FormLikeAPI.pushFieldValue
495```
496​
497***
498​
499### removeFieldValue()
500​
501```ts
502removeFieldValue<TField>(
503 field,
504 index,
505opts?): Promise<void>;
506```
507​
508Defined in: [packages/form-core/src/FieldGroupApi.ts:464](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldGroupApi.ts#L464)
509​
510Removes a value from an array field at the specified index.
511​
512#### Type Parameters
513​
514##### TField
515​
516`TField` *extends* `string`
517​
518#### Parameters
519​
520##### field
521​
522`TField`
523​
524##### index
525​
526`number`
527​
528##### opts?
529​
530`UpdateMetaOptions`
531​
532#### Returns
533​
534`Promise`\<`void`\>
535​
536#### Implementation of
537​
538```ts
539FormLikeAPI.removeFieldValue
540```
541​
542***
543​
544### replaceFieldValue()
545​
546```ts
547replaceFieldValue<TField>(
548 field,
549 index,
550 value,
551opts?): Promise<void>;
552```
553​
554Defined in: [packages/form-core/src/FieldGroupApi.ts:442](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldGroupApi.ts#L442)
555​
556Replaces a value into an array field at the specified index.
557​
558#### Type Parameters
559​
560##### TField
561​
562`TField` *extends* `string`
563​
564#### Parameters
565​
566##### field
567​
568`TField`
569​
570##### index
571​
572`number`
573​
574##### value
575​
576[`DeepValue`](../type-aliases/DeepValue.md)\<`TFieldGroupData`, `TField`\> *extends* `any`[] ? `any`[] & [`DeepValue`](../type-aliases/DeepValue.md)\<`TFieldGroupData`, `TField`\>\[`number`\] : `never`
577​
578##### opts?
579​
580`UpdateMetaOptions`
581​
582#### Returns
583​
584`Promise`\<`void`\>
585​
586#### Implementation of
587​
588```ts
589FormLikeAPI.replaceFieldValue
590```
591​
592***
593​
594### resetField()
595​
596```ts
597resetField<TField>(field): void;
598```
599​
600Defined in: [packages/form-core/src/FieldGroupApi.ts:518](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldGroupApi.ts#L518)
601​
602Resets the field value and meta to default state
603​
604#### Type Parameters
605​
606##### TField
607​
608`TField` *extends* `string`
609​
610#### Parameters
611​
612##### field
613​
614`TField`
615​
616#### Returns
617​
618`void`
619​
620#### Implementation of
621​
622```ts
623FormLikeAPI.resetField
624```
625​
626***
627​
628### setFieldMeta()
629​
630```ts
631setFieldMeta<TField>(field, updater): void;
632```
633​
634Defined in: [packages/form-core/src/FieldGroupApi.ts:370](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldGroupApi.ts#L370)
635​
636Updates the metadata of the specified field.
637​
638#### Type Parameters
639​
640##### TField
641​
642`TField` *extends* `string`
643​
644#### Parameters
645​
646##### field
647​
648`TField`
649​
650##### updater
651​
652[`Updater`](../type-aliases/Updater.md)\<`AnyFieldLikeMetaBase`\>
653​
654#### Returns
655​
656`void`
657​
658#### Implementation of
659​
660```ts
661FormLikeAPI.setFieldMeta
662```
663​
664***
665​
666### setFieldValue()
667​
668```ts
669setFieldValue<TField>(
670 field,
671 updater,
672 opts?): void;
673```
674​
675Defined in: [packages/form-core/src/FieldGroupApi.ts:380](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldGroupApi.ts#L380)
676​
677Sets the value of the specified field and optionally updates the touched state.
678​
679#### Type Parameters
680​
681##### TField
682​
683`TField` *extends* `string`
684​
685#### Parameters
686​
687##### field
688​
689`TField`
690​
691##### updater
692​
693[`Updater`](../type-aliases/Updater.md)\<[`DeepValue`](../type-aliases/DeepValue.md)\<`TFieldGroupData`, `TField`\>\>
694​
695##### opts?
696​
697`UpdateMetaOptions`
698​
699#### Returns
700​
701`void`
702​
703#### Implementation of
704​
705```ts
706FormLikeAPI.setFieldValue
707```
708​
709***
710​
711### swapFieldValues()
712​
713```ts
714swapFieldValues<TField>(
715 field,
716 index1,
717 index2,
718 opts?): void;
719```
720​
721Defined in: [packages/form-core/src/FieldGroupApi.ts:477](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldGroupApi.ts#L477)
722​
723Swaps the values at the specified indices within an array field.
724​
725#### Type Parameters
726​
727##### TField
728​
729`TField` *extends* `string`
730​
731#### Parameters
732​
733##### field
734​
735`TField`
736​
737##### index1
738​
739`number`
740​
741##### index2
742​
743`number`
744​
745##### opts?
746​
747`UpdateMetaOptions`
748​
749#### Returns
750​
751`void`
752​
753#### Implementation of
754​
755```ts
756FormLikeAPI.swapFieldValues
757```
758​
759***
760​
761### validateAllFields()
762​
763```ts
764validateAllFields(cause): Promise<unknown[]>;
765```
766​
767Defined in: [packages/form-core/src/FieldGroupApi.ts:522](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldGroupApi.ts#L522)
768​
769#### Parameters
770​
771##### cause
772​
773`ValidationCause`
774​
775#### Returns
776​
777`Promise`\<`unknown`[]\>
778​
779#### Implementation of
780​
781```ts
782FormLikeAPI.validateAllFields
783```
784​
785***
786​
787### validateArrayFieldsStartingFrom()
788​
789```ts
790validateArrayFieldsStartingFrom<TField>(
791 field,
792 index,
793cause): Promise<unknown[]>;
794```
795​
796Defined in: [packages/form-core/src/FieldGroupApi.ts:314](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldGroupApi.ts#L314)
797​
798Validates the children of a specified array in the form starting from a given index until the end using the correct handlers for a given validation type.
799​
800#### Type Parameters
801​
802##### TField
803​
804`TField` *extends* `string`
805​
806#### Parameters
807​
808##### field
809​
810`TField`
811​
812##### index
813​
814`number`
815​
816##### cause
817​
818`ValidationCause`
819​
820#### Returns
821​
822`Promise`\<`unknown`[]\>
823​
824#### Implementation of
825​
826```ts
827FormLikeAPI.validateArrayFieldsStartingFrom
828```
829​
830***
831​
832### validateField()
833​
834```ts
835validateField<TField>(field, cause): any[] | Promise<any[]>;
836```
837​
838Defined in: [packages/form-core/src/FieldGroupApi.ts:331](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldGroupApi.ts#L331)
839​
840Validates a specified field in the form using the correct handlers for a given validation type.
841​
842#### Type Parameters
843​
844##### TField
845​
846`TField` *extends* `string`
847​
848#### Parameters
849​
850##### field
851​
852`TField`
853​
854##### cause
855​
856`ValidationCause`
857​
858#### Returns
859​
860`any`[] \| `Promise`\<`any`[]\>
861​
862#### Implementation of
863​
864```ts
865FormLikeAPI.validateField
866```