feat(react-form): Add `withFieldGroup` #1469

LeCarbonator · 2025-04-30T19:51:32Z

Todos

Implementation
Unit tests
Documentation
Fixes

This PR implements a variation of withForm that can be used to create form groups. This form group allows extending defaultValues and has no expectations of form level validators.

This distinguishes it both from withForm as well as instantiations of forms.

Here's an extract of the documentation:

Reusing groups of fields in multiple forms

Sometimes, a pair of fields are so closely related that it makes sense to group and reuse them — like the password example listed in the linked fields guide. Instead of repeating this logic across multiple forms, you can utilize the withFieldGroup higher-order component.

Unlike withForm, validators cannot be specified and could be any value.
Ensure that your fields can accept unknown error types.

Rewriting the passwords example using withFieldGroup would look like this:

const { useAppForm, withForm, withFieldGroup } = createFormHook({
  fieldComponents: {
    TextField,
    ErrorInfo,
  },
  formComponents: {
    SubscribeButton,
  },
  fieldContext,
  formContext,
})

type PasswordFields = {
  password: string
  confirm_password: string
}

// These default values are not used at runtime, but the keys are needed for mapping purposes.
// This allows you to spread `formOptions` without needing to redeclare it.
const defaultValues: PasswordFields = {
  password: '',
  confirm_password: '',
}

const FieldGroupPasswordField = withFieldGroup({
  defaultValues,
  // You may also restrict the group to only use forms that implement this submit meta.
  // If none is provided, any form with the right defaultValues may use it.
  // onSubmitMeta: { action: '' }

  // Optional, but adds props to the `render` function in addition to `form`
  props: {
    // These default values are also for type-checking and are not used at runtime
    title: 'Password',
  },
  // Internally, you will have access to a `group` instead of a `form`
  render: function Render({ group, title }) {
    // access reactive values using the group store
    const password = useStore(group.store, (state) => state.values.password)
    // or the form itself
    const isSubmitting = useStore(
      group.form.store,
      (state) => state.isSubmitting,
    )

    return (
      <div>
        <h2>{title}</h2>
        {/* Groups also have access to Field, Subscribe, Field, AppField and AppForm */}
        <group.AppField name="password">
          {(field) => <field.TextField label="Password" />}
        </group.AppField>
        <group.AppField
          name="confirm_password"
          validators={{
            onChangeListenTo: ['password'],
            onChange: ({ value, fieldApi }) => {
              // The form could be any values, so it is typed as 'unknown'
              const values: unknown = fieldApi.form.state.values
              // use the group methods instead
              if (value !== group.getFieldValue('password')) {
                return 'Passwords do not match'
              }
              return undefined
            },
          }}
        >
          {(field) => (
            <div>
              <field.TextField label="Confirm Password" />
              <field.ErrorInfo />
            </div>
          )}
        </group.AppField>
      </div>
    )
  },
})

We can now use these grouped fields in any form that implements the default values:

// You are allowed to extend the group fields as long as the
// existing properties remain unchanged
type Account = PasswordFields & {
  provider: string
  username: string
}

// You may nest the group fields wherever you want
type FormValues = {
  name: string
  age: number
  account_data: PasswordFields
  linked_accounts: Account[]
}

const defaultValues: FormValues = {
  name: '',
  age: 0,
  account_data: {
    password: '',
    confirm_password: '',
  },
  linked_accounts: [
    {
      provider: 'TanStack',
      username: '',
      password: '',
      confirm_password: '',
    },
  ],
}

function App() {
  const form = useAppForm({
    defaultValues,
    // If the group didn't specify an `onSubmitMeta` property,
    // the form may implement any meta it wants.
    // Otherwise, the meta must be defined and match.
    onSubmitMeta: { action: '' },
  })

  return (
    <form.AppForm>
      <PasswordFields
        form={form}
        // You must specify where the fields can be found
        fields="account_data"
        title="Passwords"
      />
      <form.Field name="linked_accounts" mode="array">
        {(field) =>
          field.state.value.map((account, i) => (
            <PasswordFields
              key={account.provider}
              form={form}
              // The fields may be in nested fields
              fields={`linked_accounts[${i}]`}
              title={account.provider}
            />
          ))
        }
      </form.Field>
    </form.AppForm>
  )
}

Mapping field group values to a different field

You may want to keep the password fields on the top level of your form, or rename the properties for clarity. You can map field group values
to their true location by changing the field property:

Important

Due to TypeScript limitations, field mapping is only allowed for objects. You can use records or arrays at the top level of a field group,
but you will not be able to map the fields.

// To have an easier form, you can keep the fields on the top level
type FormValues = {
  name: string
  age: number
  password: string
  confirm_password: string
}

const defaultValues: FormValues = {
  name: '',
  age: 0,
  password: '',
  confirm_password: '',
}

function App() {
  const form = useAppForm({
    defaultValues,
  })

  return (
    <form.AppForm>
      <PasswordFields
        form={form}
        // You can map the fields to their equivalent deep key
        fields={{
          password: 'password',
          confirm_password: 'confirm_password',
          // or map them to differently named keys entirely
          // 'password': 'name'
        }}
        title="Passwords"
      />
    </form.AppForm>
  )
}

If you expect your fields to always be at the top level of your form, you can create a quick map
of your field groups using a helper function:

const defaultValues: PasswordFields = {
  password: '',
  confirm_password: '',
}

const passwordFields = createFieldMap(defaultValues)
/* This generates the following map:
 {
    'password': 'password',
    'confirm_password': 'confirm_password'
 }
*/

// Usage:
<PasswordFields
  form={form}
  fields={passwordFields}
  title="Passwords"
/>

nx-cloud · 2025-04-30T19:51:54Z

View your CI Pipeline Execution ↗ for commit 8ce40fe.

Command	Status	Duration	Result
`nx affected --targets=test:sherif,test:knip,tes...`	✅ Succeeded	1m 20s	View ↗
`nx run-many --target=build --exclude=examples/**`	✅ Succeeded	23s	View ↗

☁️ Nx Cloud last updated this comment at 2025-06-02 11:15:10 UTC

pkg-pr-new · 2025-04-30T19:52:57Z

More templates

@tanstack/angular-form

npm i https://pkg.pr.new/@tanstack/angular-form@1469

@tanstack/form-core

npm i https://pkg.pr.new/@tanstack/form-core@1469

@tanstack/lit-form

npm i https://pkg.pr.new/@tanstack/lit-form@1469

@tanstack/react-form

npm i https://pkg.pr.new/@tanstack/react-form@1469

@tanstack/solid-form

npm i https://pkg.pr.new/@tanstack/solid-form@1469

@tanstack/svelte-form

npm i https://pkg.pr.new/@tanstack/svelte-form@1469

@tanstack/vue-form

npm i https://pkg.pr.new/@tanstack/vue-form@1469

commit: 8ce40fe

LeCarbonator · 2025-04-30T19:58:32Z

Issues that could be addressed:

~~If the instantiated form has onSubmitMeta, it's no longer compatible with the form group. Perhaps if onSubmitMeta is unset and/or not called inside form Group, it should allow it outside.~~

This has now been addressed. If onSubmitMeta is unset, any value will do. If it is set, you must match it exactly.

While the previous separate implementation was compatible with AppForm, users wouldn't have been able to use any field/form components in the render itself. This commit allows them to do that, at the expense of not being compatible with useForm.

LeCarbonator · 2025-05-01T11:55:18Z

The unit tests should be reusable in case this isn't the desired approach.

codecov · 2025-05-01T11:57:39Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 90.10%. Comparing base (75a442d) to head (8ce40fe).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1469      +/-   ##
==========================================
+ Coverage   89.24%   90.10%   +0.86%     
==========================================
  Files          31       33       +2     
  Lines        1432     1557     +125     
  Branches      366      380      +14     
==========================================
+ Hits         1278     1403     +125     
  Misses        137      137              
  Partials       17       17

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

LeCarbonator · 2025-05-01T12:04:34Z

Related PR: #1334

LeCarbonator · 2025-05-02T04:48:04Z

Something to consider:

You cannot nest these form groups (Address form group vs. Address form group in an array)
They can be conflicting with other groups (two groups sharing the name path). This can be averted by assuming a path namespace like address.name

This type will help with a lens API for forms so that only names leading to the subset data are allowed.

LeCarbonator · 2025-05-08T18:00:00Z

#1475 sounded like an interesting idea, so I'll try to tinker with that and come up with unit tests. The note at the top of the PR still applies.

…k-form into form-group-api

LeCarbonator · 2025-05-10T16:26:27Z

Strange, the derived state from the form lens isn't updating ...
Looks like it's because i'm not mounting it.

Issue: React input unfocuses when changing input. Unsure why.

…m into form-group-api

the method appears to be a helper function for form.reset, which is accessible from the field group API. There does not seem to be a good reason to port this method from FormApi.

MPiland · 2025-06-05T00:39:59Z

@LeCarbonator I've been toying this PR (I know it's not done) because it's exactly what I need. I'm not an experienced developer by any means, but I am a product manager by trade and so I'm used to thinking about user experience or in this case developer experience. Can I suggest that instead a fields prop that either takes a string or an object of key value pairs where you map a form property to the group property, could we instead have a group prop and we pass the actual form object to a group prop or map the destination property to the form property directly? That could be more intuitive since we pass the form prop to the withForm hook and this would feel similar in experience. I don't know the feasibility with that and maintaining type safety, though.

LeCarbonator · 2025-06-05T05:51:44Z

@MPiland could you provide a code snippet of what that structure may look like? It doesn't need to be feasible, just a snippet of what you envisioned the API to be

users are able to do conditional rendering, but TS generally doesn't pick up on it. Therefore, while it is less type safe, it allows users to use field groups in more locations than previously possible.

MPiland · 2025-06-08T00:59:59Z

@LeCarbonator I think there's a couple ways that could maybe work. The prop could be just named group that could either accept an object or an object of properties mapped to form properties. This would probably require a form subscribe.

/* As object */
<form.Subscribe select={(state) => state.values)}>
  {(values) => {
    <Auth group={values.auth} form={form}  />
   }
</form.Subscribe>

/* As properties mapped to form properties */
<form.Subscribe select={(state) => state.values)}>
  {(values) => {
    <Auth group={{username: values.username, password: values.password}} form={form}  />
   }
</form.Subscribe>

Alternatively, you could add a new option to the createFormHook called groupComponents. They could be called similar to field components, but their name prop could take a string or an object of key values similar to how the withFieldGroup works. Then it could use a useGroupContext. This is all completely brainstorming so it may not be possible. But you could call it like

<form.AppGroup name='auth'>
  {({ AuthGroup }) => (
    <AuthGroup {...props} />
  )} />
</form.AppGroup>

/* or */

<form.AppGroup name={{ username: 'username', password: 'password' }}>
  {( group ) => (
    <group.AuthGroup {...props} />
  )} />
</form.AppGroup>

/* Defining it could be like this */

export const AuthGroup = () => {
  const {state, group, AppField} = useGroupContext<AuthGroupType>()

  <state.AppField name='password'>
    {( field) => (
      <field.TextInput label='Password' />
    )}
  </state.AppField>
}

/* or */

<form.Group name='auth'> // Alternatively <form.Group name={{ password: 'password' }}>
  {( group ) => (
    <group.Field name='password'>
      .....
    </group.Field>
  )}
</form.Group>

The current approach still works, though, and if that makes more sense to other users, I'm ok being told I'm wrong. I'm just throwing out some ideas. I really like this library. It took me a minute to get it, but once I did it's very intuitive. I just need this last group feature to be able to use it.

LeCarbonator · 2025-06-08T07:53:26Z

@MPiland Alright, here's my thoughts on the snippets:

<form.Subscribe select={(state) => state.values)}>
  {(values) => {
    <Auth group={values.auth} form={form}  />
   }
</form.Subscribe>

I'm heavily against this implementation. The reason is that field groups aren't just displaying values, they map fields called within to the form outside. This would force it to be a one-way street which goes against a lot of the features other users want.

As for <form.AppGroup/>, I can see it working, but the benefits aren't very clear to me.
The reason AppField exists is because you have more flexibility for how you implement it:

/* Do you want granular control? */
<form.AppField name="firstName">
  {field => <>
     <label>First Name</label>
     <field.TextInput />
     <field.Feedback />
  </>}
</form.AppField>

/* Or wrap it all in a component? */
<form.AppField name="firstName">
  {field => <field.TextInput showFeedback label="First Name" />}
</form.AppField>

Field groups don't really fit that category, as they're meant to do the work themselves. Once you have the field group, there's really only one way to use it, and that is like you showed:

/* Combinations don't really exist. Either you use the field group or you don't */
<form.AppGroup name='auth'>
  {({ AuthGroup }) => (
    <AuthGroup {...props} />
  )} />
</form.AppGroup>

That's why I prefer the HOC implementation. Hopefully it's clear what I'm trying to convey.

MPiland · 2025-06-08T16:53:28Z

@LeCarbonator That all makes sense to me! I will defer to your expertise. I think the original way works as well. I appreciate you entertaining my thoughts!

TheoJV24 · 2025-06-27T09:56:41Z

Will this feature work if multiple forms share the same UI but have different fields?
In our case, each form is divided into tabs, each rendering a form with Section A and Section B.
Section B shares the same UI across forms, but some fields are present only in certain forms.

Example:
Cycling From — Section B: calories, elevationGain, distance
Swimming Form — Section B: calories, distance
Gym Form — Section B: calories

LeCarbonator · 2025-06-27T10:09:42Z

Will this feature work if multiple forms share the same UI but have different fields? In our case, each form is divided into tabs, each rendering a form with Section A and Section B. Section B shares the same UI across forms, but some fields are present only in certain forms.

Example: Cycling From — Section B: calories, elevationGain, distance Swimming Form — Section B: calories, distance Gym Form — Section B: calories

Not with its current implementation, no. The intent of this feature is to group multiple fields together so they can all be reused. The Section B you describe is not consistent across forms, but is instead a collection of a calories field, a elevationGain field and a distance field.
Since it's only single fields that remain consistent across forms, consider using a Field Component instead.

An example usage of this field group would be:

Section: calories, elevationGain, distance

Cycling Form - calories, elevationGain, distance
Swimming Form - data.calories, data.elevationGain, data.distance (namespaced with data)
Gym Form - gymCalories, gymElevationGain, gymDistance (mapped to calories, elevationGain, distance)

feat: add createFormGroup

187db7b

LeCarbonator added 3 commits May 1, 2025 11:49

chore: add unit tests for createFormGroup types

072898e

chore: add unit test for createFormGroup

9add0bb

LeCarbonator changed the title ~~Draft: Suggestion for Form Group API~~ feat(react-form): Add Form Group API May 1, 2025

LeCarbonator marked this pull request as ready for review May 1, 2025 11:46

chore: export CreateFormGroupProps

6974927

Merge branch 'main' into form-group-api

a0238ed

LeCarbonator marked this pull request as draft May 5, 2025 07:44

LeCarbonator added 2 commits May 8, 2025 14:47

add DeepKeysOfType util type

edd4fcb

This type will help with a lens API for forms so that only names leading to the subset data are allowed.

feat: add initial FormLensApi draft

5c7abbf

LeCarbonator added 10 commits May 8, 2025 20:03

Merge branch 'main' of github.com:TanStack/form into form-group-api

61c7049

chore: add FormLensApi tests batch

15eecd4

fix(form-core): fix form.resetField() ignoring nested fields

3e99f6f

Merge branch 'fix-TanStackgh-1496' of github.com:LeCarbonator/tanstac…

b8b1179

…k-form into form-group-api

chore: complete form-core unit test for FormLensApi

3d14dee

feat: add react adapter to form lens api

1900857

fix: fix names for lens.Field and add test

1eb15e9

chore: export WithFormLensProps

400abf9

Merge branch 'main' into form-group-api

8484d79

feat: add Subscribe and store to form lens

dfe6f03

LeCarbonator and others added 12 commits May 30, 2025 15:06

refactor: move path concatenation to utils

3d4afea

Merge branch 'main' of github.com:TanStack/form into form-group-api

6b1e2e5

chore: move useLens to own file and rename

ca35b16

feat: add FieldsMap and createFieldMap utils

6d6d24c

chore: migrate (most) lens references to field group

ff55fa5

chore: finalize migration from lens to field group

4099ac5

ci: apply automated fixes and generate docs

69bec92

chore: remove accidental test file

38e6db2

Merge branch 'form-group-api' of github.com:LeCarbonator/tanstack-for…

5b2c763

…m into form-group-api

chore: add some unit tests for field mapping

69e313b

chore: add unit tests

129cf17

docs: update docs to use group

15dca70

LeCarbonator changed the title ~~feat(react-form): Add withFormLens~~ feat(react-form): Add withFieldGroup Jun 1, 2025

LeCarbonator added 4 commits June 1, 2025 11:22

docs: add caveat with field mapping

59bc7cd

docs: fix weird line break in alert text

8da753b

Merge branch 'main' into form-group-api

98aa36b

revert: remove FieldGroupApi#resetFieldMeta

8ce40fe

the method appears to be a helper function for form.reset, which is accessible from the field group API. There does not seem to be a good reason to port this method from FormApi.

LeCarbonator mentioned this pull request Jun 2, 2025

Allow withForm components to accept extending properties #1334

Closed

LeCarbonator mentioned this pull request Jun 5, 2025

withForm types break if defaultValues includes any extra field #1296

Open

LeCarbonator added 2 commits June 6, 2025 09:33

refactor: allow null or undefined for field group keys

51a1942

users are able to do conditional rendering, but TS generally doesn't pick up on it. Therefore, while it is less type safe, it allows users to use field groups in more locations than previously possible.

chore: add FieldGroupApi.test-d.ts

4daaa6b

LeCarbonator requested a review from crutchcorn June 8, 2025 11:30

danhaus mentioned this pull request Jun 29, 2025

[Feature Request]: Form Groups #419

Open

Uh oh!

feat(react-form): Add withFieldGroup #1469

Are you sure you want to change the base?

feat(react-form): Add withFieldGroup #1469

Conversation

LeCarbonator commented Apr 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Todos

Reusing groups of fields in multiple forms

Mapping field group values to a different field

Uh oh!

nx-cloud bot commented Apr 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new bot commented Apr 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

LeCarbonator commented Apr 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

LeCarbonator commented May 1, 2025

Uh oh!

codecov bot commented May 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

LeCarbonator commented May 1, 2025

Uh oh!

LeCarbonator commented May 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

LeCarbonator commented May 8, 2025

Uh oh!

LeCarbonator commented May 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

MPiland commented Jun 5, 2025

Uh oh!

LeCarbonator commented Jun 5, 2025

Uh oh!

MPiland commented Jun 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

LeCarbonator commented Jun 8, 2025

Uh oh!

MPiland commented Jun 8, 2025

Uh oh!

TheoJV24 commented Jun 27, 2025

Uh oh!

LeCarbonator commented Jun 27, 2025

Section: calories, elevationGain, distance

Uh oh!

Uh oh!

feat(react-form): Add `withFieldGroup` #1469

feat(react-form): Add `withFieldGroup` #1469

LeCarbonator commented Apr 30, 2025 •

edited

Loading

nx-cloud bot commented Apr 30, 2025 •

edited

Loading

pkg-pr-new bot commented Apr 30, 2025 •

edited

Loading

LeCarbonator commented Apr 30, 2025 •

edited

Loading

codecov bot commented May 1, 2025 •

edited

Loading

LeCarbonator commented May 2, 2025 •

edited

Loading

LeCarbonator commented May 10, 2025 •

edited

Loading

MPiland commented Jun 8, 2025 •

edited

Loading