feat: Allow restricting field component to field value

[LeCarbonator]

Related issue: #1506

This PR implements a way to create 'branded' field components. Those special field components may only be used if the AppField's value matches it.

TODOS

• Check need for implementation (and implement)
  • React
  • Solid
  • Angular
• Amend documentation of Form Composition
  • React
  • Solid
  • Angular
• Unit tests

The issue

interface TextFieldProps {
  label: string
}

function TextField(props: TextFieldProps) {
  // we assume our field will be of type string
  const field = useFieldContext<string>();

  return <></>;
}

const { useAppForm } = createFormHook({
  fieldContext,
  formContext,
  fieldComponents: {
    TextField
  },
  formComponents: {},
})

function App() {
  const form = useAppForm({
    defaultValues: {
      a: '',
      b: 0,
    },
  })
 

  return (
    <>
      <form.AppField name="a">
        {(field) => {
          // okay, because 'a' is a string
          return <field.TextField label="" />;
        }}
      </form.AppField>
      <form.AppField name="b">
        {(field) => {
          // oops! 'b' is a number, not a string. No error shows up
          return <field.TextField label="" />;
        }}
      </form.AppField>
    </>
  )
}

The solution

The PR addresses it as follows (feedback is appreciated!):

interface TextFieldProps {
  label: string
}

function TextField(props: TextFieldProps) {
  // we assume our field will be of type string
  const field = useFieldContext<string>();

  return <></>;
}

// we're creating a field component restricted to strings, with the properties of TextFieldProps
const TextFieldComponent = createFieldComponent<string, TextFieldProps>(TextField);

const { useAppForm } = createFormHook({
  fieldContext,
  formContext,
  fieldComponents: {
    TextField: TextFieldComponent,
    OldTextField: TextField
  },
  formComponents: {},
})

function App() {
  const form = useAppForm({
    defaultValues: {
      a: '',
      b: 0,
    },
  })
 

  return (
    <>
      <form.AppField name="a">
        {(field) => (
          <>
             {/* Okay, because 'a' is a string */}
             <field.TextField label="" />
             <field.OldTextField label="" />
          </>
        )}
      </form.AppField>
      <form.AppField name="b">
        {(field) => (
          <>
            {/* Error! TextField cannot be used on number fields */}
            <field.TextField label="" />
             {/* Directly passed compoents are considered 'global' */}
             <field.OldTextField />
          </>
        }}
      </form.AppField>
    </>
  )
}

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 24f9ef3

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

---

☁️ Nx Cloud last updated this comment at 2025-07-09 05:10:41 UTC

[pkg-pr-new]

More templates

• @tanstack/form-example-angular-array
• @tanstack/form-example-angular-large-form
• @tanstack/form-example-angular-simple
• @tanstack/form-example-lit-simple
• @tanstack/form-example-lit-ui-libraries
• @tanstack/form-example-react-array
• @tanstack/form-example-react-compiler
• @tanstack/field-errors-from-form-validators
• @tanstack/form-example-react-large-form
• @tanstack/form-example-react-next-server-actions
• @tanstack/form-example-react-query-integration
• @tanstack/form-example-remix
• @tanstack/form-example-react-simple
• @tanstack/form-example-react-standard-schema
• @tanstack/form-example-react-tanstack-start
• @tanstack/form-example-react-ui-libraries
• @tanstack/form-example-solid-array
• @tanstack/form-example-solid-large-form
• @tanstack/form-example-solid-simple
• @tanstack/form-example-svelte-array
• @tanstack/form-example-svelte-simple
• @tanstack/form-example-vue-array
• @tanstack/form-example-vue-simple

@tanstack/angular-form

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

@tanstack/form-core

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

@tanstack/lit-form

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

@tanstack/react-form

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

@tanstack/solid-form

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

@tanstack/svelte-form

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

@tanstack/vue-form

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

commit: 24f9ef3

[codecov]

Codecov Report

Attention: Patch coverage is 33.33333% with 2 lines in your changes missing coverage. Please review.

Project coverage is 43.03%. Comparing base (6510d8b) to head (24f9ef3).
Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
packages/react-form/src/createFormHook.tsx	33.33%	2 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##             main    #1606       +/-   ##
===========================================
- Coverage   89.55%   43.03%   -46.52%     
===========================================
  Files          34       13       -21     
  Lines        1493      158     -1335     
  Branches      370       26      -344     
===========================================
- Hits         1337       68     -1269     
+ Misses        139       79       -60     
+ Partials       17       11        -6     

☔ 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.