TanStack / TanStack/form

formOptions missing type inference leads to incorrect inferred types in subforms (withForm)

Open
#1,273 4 comments 8 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area: types scope: react type: bug v1
Dominant language
TypeScript
Stars
6.7k
Forks
682
Avg merge
5d 18h
Merged PRs (30d)
7

Description

Describe the bug

Currently, defining validators within the formOptions function does not allow proper type inference from defaultOptions. To retain type inference, users are forced to define validators within useAppForm at the top-level form.

However, this causes a problem for sub-form components that use withForm. If these sub-forms rely on the return type of formOptions, they do not inherit the validators defined in useAppForm. As a result, fields within the sub-forms lack access to the form-level validators, leading to incorrect type inference. (No issues at runtime).

Your minimal, reproducible example

https://stackblitz.com/edit/tanstack-form-ajwjukhq?file=src%2Ffeatures%2Fpeople%2Fshared-form.tsx

Steps to reproduce

Simply go to shared-form.tsx and notice the value prop for validators > onChange is any.
This illustrates the lack of type inference within formOptions.

Within this second stackblitz you can see what I mean about incorrect type inference if defining validators within useAppForm:

https://stackblitz.com/edit/tanstack-form-oennwahz?file=src%2Ffeatures%2Fpeople%2Faddress-fields.tsx

For this one, notice how within useAppField, we defined an error for that address.line1 that returns a number!
We then defined a validator at the field level for the same field that returns string.

Given we made it so TextField accepts an error prop of type string | undefined, we would expect a type error if we try to pass field.state.errors[0], because the correct type should be string | number | undefined. However the inferred type for fiels.state.errors[0] is string | undefined because it has no clue that we defined validators within useAppForm.

This could result in runtime bugs as the inferred type is NOT what's at runtime.

Expected behavior

We would expect for the formOptions function to allow defining validators with type inference available. Additionally improving the types/documentation for withForm, and useAppForm to include the following:

Defining any options within useAppForm means they will not flow down to subforms which is leading to a lot of discussions/issues raised on the discord and here.

How often does this bug happen?

Every time

Screenshots or Videos

No type inference within formOptions:
Image
Type inference when defining validators within useAppForm:
Image

Also recommend seeing this discord thread with @crutchcorn for more context: https://discord.com/channels/719702312431386674/1349567229305557002/1349567229305557002

Platform

Consistent issue with any typescript environment.

TanStack Form adapter

react-form

TanStack Form version

v1.0.5

TypeScript version

No response

Additional context

No response

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the shared-form.tsx and address-fields.tsx examples in the linked StackBlitz reproductions, then trace how formOptions, useAppForm, and withForm carry validator types into subforms. Done means validators defined through formOptions remain available to subforms and the inferred error type includes both form-level and field-level validator results.

Written by the indexing model from the issue text.

Assessment

Tech stack
react, typescript
Domain
frontend
Issue type
Bug
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.