`form.Subscribe` API inconsistency: children prop vs JSX children

[Criezc]

Describe the bug

form.Subscribe doesn't accept children as a prop attribute, only as JSX children, but the examples given showing that it accept children as props.

When using form.Subscribe with a selector prop, passing the render function via the children prop attribute doesn't work. The component only works when the render function is passed as JSX children (between opening and closing tags).

This creates an inconsistency with other form components like form.AppField, which accept children as a prop attribute.

Eventually both pattern works as expected but typescript complaining about the error.

Your minimal, reproducible example

https://stackblitz.com/edit/vitejs-vite-of4hmkxe?file=src%2FApp.tsx

Steps to reproduce

1. Create a form using withForm or useForm
2. Use form.Subscribe with a selector prop
3. Pass the render function via the children prop attribute

<form.Subscribe
  children={(title) => {
    return <div>{title}</div>
  }}
  selector={(state) => state.values.title}
/>

Expected behavior

The form.Subscribe component should accept the render function via the children prop attribute, similar to how form.AppField works:

// This pattern should work (but currently doesn't)
<form.Subscribe
  children={(title) => <div>{title}</div>}
  selector={(state) => state.values.title}
/>

// This pattern works for form.AppField
<form.AppField
  children={(field) => <input {...field} />}
  name="title"
/>

How often does this bug happen?

Every time

Screenshots or Videos

Selector error:

Props error:

Platform

• OS: Mac OS
• Version: Sequoia 15.5

TanStack Form adapter

react-form

TanStack Form version

^1.27.7

TypeScript version

^5.7.2

Additional context

No response

[LeCarbonator]

This happens because of how React props work.

To put it simply, the props look sort of like this:

interface Props<T> {
  selector: (state: FormState) => T;
  children: (value: T) => JSX.Element
}

The order here is important. If children was placed first, it would be inferred as unknown and reject your selector.

If the selector comes first, then the children properly accepts that value.

This is fine with JSX children, since children will always be second:

<form.Subscribe selector={state => state.isSubmitting}>
  {thisIsABool => <>{thisIsABool}</>}
</form.Subscribe>

The example you posted is the "wrong" order though, and will cause an error. You can still make it work, as long as children is placed after selector:

<form.Subscribe 
  selector={state => state.isSubmitting}
  children={thisIsABool => <>{thisIsABool}</>}
/>

The important thing to note: children as prop vs. as JSX child is a semantic difference only. Both are valid in React and not in our control.

[LeCarbonator]

Here's a TypeScript playground to demonstrate the inference.

There's not much we can do about this since it is related to React and not TanStack Form. If you have ideas on how to approach this differently, let us know.

[Criezc]

Ah I see!, Thanks for the clarification. I wasn't aware that TypeScript infers generic types sequentially through props and I just learned today. This make sense now, the prop order determines the inference order, while JSX children always processed after all props.

In my case, the props were being automatically reordered by Biome. which was moving children before selector and causing TypeScript error.

Thank you very much @LeCarbonator !

[LeCarbonator]

I had a suspicion that the property sorting was the cause. We've had reports for Biome environments before, and it's one of the few reasons that property sorting can be iffy in TypeScript.

Keep in mind that TanStack Router can also change behaviour if you change the order of properties to be alphabetical.