Form Context Not Propagating Through `<form.AppForm>`

[aress31]

Describe the bug

I have been reading the documentation and browsing issues here, but I still cannot determine whether this behaviour is a bug or an intentional design choice. <form.AppForm> does not appear to behave like a context provider at all, despite the expectation that it should.

Your minimal, reproducible example

N/A

Steps to reproduce

Consider the following simplified example:

function Root() {
  // --- SNIP ---
  const form = useAppForm({
    defaultValues: {
      foo: data?.foo ?? "",
      bar: "bar",
    } as ProviderInsertFormValues,
    onSubmit: async ({ value }) => {
      console.log(values);
    },
    validators: {
      onChange: ProviderInsertSchema,
    },
  });
  // --- SNIP ---

  return (
    <form.AppForm>
      <form onSubmit={form.handleSubmit}>
        <XFields />
      </form>
    </form.AppForm>
  );
}

Then in Child:

export default function Child() {
  const {
    Field,
    state: { isSubmitting },
  } = useFormContext();

  return (
    <FieldSet disabled={isSubmitting}>
      <Field name="apiKey">
        {(field) => (
          <field.InputAdornmentField
            label="Foo"
            placeholder="foo"
          />
        )}
      </Field>
    </FieldSet>
  );
}

I get several type errors, for example:

1. Error for the name key

Type 'string' is not assignable to type 'never'.ts(2322)
FieldApi.d.ts(136, 5): The expected type comes from property 'name' [...]

The error indicates that name resolves to never, as if the parent form has no recognised keys. This usually means the form context is not providing any type information down the tree.

2. Error for field.InputAdornmentField

Property 'InputAdornmentField' does not exist on type 'FieldApi<...>'.ts(2339)

This suggests that the custom field components defined in the form hook are not being registered or propagated through context.

---

My components are nested several levels deep, so I rely heavily on the context provider. I have followed the documentation and this is my index.ts setup:

"use client";

import { createFormHook, createFormHookContexts } from "@tanstack/react-form";

import AsyncComboboxField from "./async-combobox-field";
import CheckboxField from "./checkbox-field";
import InputAdornmentField from "./input-adornment-field";
import SelectField from "./select-field";
import TextAreaField from "./text-area-field";

export const { fieldContext, formContext, useFieldContext, useFormContext } =
  createFormHookContexts();

export const { useAppForm } = createFormHook({
  fieldComponents: {
    AsyncComboboxField,
    CheckboxField,
    InputAdornmentField,
    SelectField,
    TextAreaField,
  },
  fieldContext,
  formComponents: {},
  formContext,
});

At this point I am not sure whether:

• I am missing a required wrapper or provider,
• <form.AppForm> is not intended to behave like the documentation implies, or
• there is an issue with how types are inferred when using createFormHook.

Any clarification, along with improvements to the documentation around context behaviour and type inference, would be greatly appreciated.

Expected behavior

• <form.AppForm> should provide the full form context to all nested components, including type information and registered field components.
• useFormContext() should return a correctly typed Field component and full form state within any child component.
• Field names such as "apiKey" should be validated against the form’s data shape rather than resolving to never.
• Custom field components (e.g. InputAdornmentField) should be accessible via field.InputAdornmentField when registered in createFormHook.
• Type inference should correctly propagate from the form initialisation to every descendant without needing to manually pass the form object.

How often does this bug happen?

None

Screenshots or Videos

No response

Platform

• Windows 11

TanStack Form adapter

None

TanStack Form version

1.27.1

TypeScript version

5.9.3

Additional context

No response

[crutchcorn]

You need to use withForm to preserve the TS typing; otherwise we can't ensure that the fields exist at all. Runtime shouldn't have issues with what you're doing, but TS-land will.

[aress31]

@crutchcorn Thanks for the reply. The challenge I’m running into with withForm is that it feels quite repetitive. If I understand it correctly, I need to pass formOpt as the first parameter, which largely duplicates the configuration I’ve already provided when initialising the form:

const form = useAppForm({
  defaultValues: {
    foo: data?.foo ?? "",
    bar: "bar",
  } as ProviderInsertFormValues,
  onSubmit: async ({ value }) => {
    console.log(values);
  },
  validators: {
    onChange: ProviderInsertSchema,
  },
});

Is there a way to avoid repeating defaultValues multiple times?

const FieldGroupPasswordFields = 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(props) {
    // access reactive values using the group store
    const password = useStore(
      props.group.store,
      (state) => state.values.password,
    )
    // or the form itself
    const isSubmitting = useStore(
      props.group.form.store,
      (state) => state.isSubmitting,
    )

    return (
      <div>
        <h2>{props.title}</h2>
        {/* Groups also have access to Field, Subscribe, Field, AppField and AppForm */}
        <props.group.AppField name="password">
          {(field) => <field.TextField label="Password" />}
        </props.group.AppField>
        <props.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 !== props.group.getFieldValue('password')) {
                return 'Passwords do not match'
              }
              return undefined
            },
          }}
        >
          {(field) => (
            <div>
              <field.TextField label="Confirm Password" />
              <field.ErrorInfo />
            </div>
          )}
        </props.group.AppField>
      </div>
    )
  },
})

Another issue with withForm is that I have several deeply nested components, and prop drilling quickly becomes unmanageable in those cases.

Any guidance on how best to approach this would be greatly appreciated. It’s an excellent library, and coming from RHF it already solves many of my pain points out of the box — I just need to get a handle on these typing patterns.