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

fieldgroupapi.md

810 lines14.6 KB

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