bug: `useForm` and `FormApi` require 9 generic types instead of 1 starting 0.43.0

[favna]

Describe the bug

Previously with v0.42.x the types of useForm (react hook) and FormApi (core class) had 2 generic types, with only 1 being required:

  TFormData,
  TFormValidator extends Validator<TFormData, unknown> | undefined = undefined,

Starting 0.43.0 however this has changed to 9 required generic types:

  TFormData,
  TOnMount extends undefined | FormValidateOrFn<TFormData>,
  TOnChange extends undefined | FormValidateOrFn<TFormData>,
  TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
  TOnBlur extends undefined | FormValidateOrFn<TFormData>,
  TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
  TOnSubmit extends undefined | FormValidateOrFn<TFormData>,
  TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
  TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,

Even if the form desired by the user does not have any validations they are now forced to define their strictly typed form like so:

const myForm = new FormApi<MyInterface, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined>

Which is extremely cumbersome. Furthermore, for our work project we also wrap a few Tanstack Form component with our custom Material UI components and we want those to be strictly typed, which would now become a complete flustercluck (excuse my french) with generic types.

I would really appreciate it if the defaults for the generic types could be re-introduced.

Your minimal, reproducible example

https://www.typescriptlang.org/play/?#code/JYWwDg9gTgLgBAbzgVwM4FMBi0RwL5wBmUEuA5AAIwCGAdqjQMYDWA9FOtYzALSE5kA3AChhwWjHRRCXdHACyATwAi1GomFwtcWtRDoAXHAZRxAcxHa41M4Z3IQAIyki8oxhHrwQi7FFwAvCgYfiAAPEqqNAB8ABQImtoAJugyyAA2MABq1OnI6KhGCVZWNnYAzAAMADSJJTp6dmSY1ABuumR1+MJ4AJRAA

Steps to reproduce

1. Go to the above linked TypeScript playground
2. Go to the "errors" tab
3. See the error "Expected 9 type arguments, but got 1."

Code used on playground:

import { useForm } from '@tanstack/react-form';

interface MyData {
    name: string;
    age: number;
}

const myForm = useForm<MyData>({
    defaultValues: {
        age: 30,
        name: 'Favna'
    }
})

Expected behavior

Expected behaviour is that the code above works just fine, regardless of the 8 missing generic types.

How often does this bug happen?

Every time

Screenshots or Videos

No response

Platform

• OS: MacOS
• Version: Seqouia 15.3.1

TanStack Form adapter

react-form

TanStack Form version

0.43.2

TypeScript version

5.7.3

Additional context

No response

[crutchcorn]

This is correct behavior and is required for many of our TS types to work properly. PRs welcomed if you can solve our types another way.

[crutchcorn]

We never intend anyone to pass anything to useForm's generics. Instead, you should be doing:

const myForm = useForm({
    defaultValues: {
        age: 30,
        name: 'Favna'
    } as MyData
})

[VibrantMoose]

In my case I don't pass generics to the hook, but I pass the myForm instance to react child components. I was using ReactFormExtendedApi in the children's props interfaces. I have multiple huge forms I had to split in multiple components, so the useForm hook is called in a parent component. Am I doing this wrong ?

EDIT: Oh.... I missed the useField hook I guess ?

[crutchcorn]

Do not use the useField hook, it's strongly suggested against using in your own codebase.

We do not currently have a good alternative API to do what you're looking for, though I have an API in mind for how to do this. However, it's unclear to me some of the edgecases.

EG:

function Parent() {
    const form = useForm({defaultValues: {firstName: ""} });

    return <Child form={form} />
}

// Imagine a new `withForm` HOC API that handles typings for you
const Child = withForm(({form}) => {
    // How do we ensure that `name` is not invalid? How do we infer the type of `field.handleChange` if we allow that?
    return <form.Field name="testing"/>
});

[favna]

This is correct behavior and is required for many of our TS types to work properly. PRs welcomed if you can solve our types another way.

That's all fine and well, but that does not address the point of:

Furthermore, for our work project we also wrap a few Tanstack Form component with our custom Material UI components and we want those to be strictly typed, which would now become a complete flustercluck (excuse my french) with generic types.

For example, this is our custom component to show form errors under input fields (CustomNotificationComponent uses Material-UI components)

import type { DeepKeys, DeepValue, FieldApi, Validator } from '@tanstack/react-form';

export interface FormErrorProps<
  TParentData,
  TName extends DeepKeys<TParentData>,
  TFieldValidator extends Validator<DeepValue<TParentData, TName>, unknown> | undefined = undefined,
  TFormValidator extends Validator<TParentData, unknown> | undefined = undefined,
  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>
> {
  readonly 'data-qa'?: string;
  readonly field: FieldApi<TParentData, TName, TFieldValidator, TFormValidator, TData>;
}

export function FormError<
  TParentData,
  TName extends DeepKeys<TParentData>,
  TFieldValidator extends Validator<DeepValue<TParentData, TName>, unknown> | undefined = undefined,
  TFormValidator extends Validator<TParentData, unknown> | undefined = undefined,
  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>
>({ field, 'data-qa': dataQa }: FormErrorProps<TParentData, TName, TFieldValidator, TFormValidator, TData>) {
  if (field.state.meta.isTouched && field.state.meta.errors.length) {
    const message = field.state.meta.errors.at(0);
    const stringMessage = typeof message === 'string' ? message : '';

    if (!stringMessage) return null;

    return <CustomNotificationComponent data-qa={dataQa ?? 'form-error'} message={stringMessage} severity='error' />;
  }

  return null;
}

The implementation with 0.42.x of this component is (code below is one of the unit tests for this component):

    const form = useForm<DummyFormData, Validator<DummyFormData, unknown>>({
      defaultValues: {
        name: 'John Connor',
        age: 35
      },

      onSubmit: formSubmitAction
    });

    return (
      <form.Field name='name'>
        {(field) => {
          // Set dummy values to the field meta
          field.state.meta.isTouched = true;
          field.state.meta.errors = ['Name is required'];

          return (
            <FormError<DummyFormData, 'name', undefined, Validator<DummyFormData, unknown>, string> field={field} />
          );
        }}
      </form.Field>
    );

Even if we were to remove the generic types from useForm, that doesn't cover the types for the field prop for FormError.

As it stands, I have no idea how to update this code to work on 0.43.0 short of just dumping any for the field prop type which is very undesirable. I strongly believe that the moment you put any in TypeScript code, you may as well not be using TypeScript at all.

[crutchcorn]

@favna can you please join our Discord and ping me in #form?

https://tlinz.com/discord

I rather suspect we're going to end up talking past each other in GH issues and just end up frustrating one another needlessly. I think you've unintentionally walked down a sad-path of Form that we've been trying to avoid, but will have some APIs to address them this week that I think you'll like.

[deniskabana]

@crutchcorn This is a very tough decision that you made for us.

Unfortunately, I second the OP. We never have any objects representing the data, as ALL of these in our entire app are received asynchronously during run-time. We however have full access to the interfaces that the objects adhere to during compile-time and for all TypeScript features our project HAS to rely on generics.

This decision seems very short-sighted. Required code in 0.43.x:

/* eslint-disable @typescript-eslint/no-explicit-any */

export type CReactFormApi<TFormData extends object> = ReactFormApi<
  TFormData,
  any,
  any,
  any,
  any,
  any,
  any,
  any,
  any,
  any
>;

export type CReactFormExtendedApi<TFormData extends object> = ReactFormExtendedApi<
  TFormData,
  any,
  any,
  any,
  any,
  any,
  any,
  any,
  any,
  any
>;

OR

const form = useForm({ defaultValues: {} as IFormSchema }); // This breaks TS and is error-prone

Can this issue be re-wised or re-visited please? Specifically for those of us who have no defaultValues when compiling TS?

[crutchcorn]

This decision is the opposite of short-sighted; it's motivated by seeing our consistent shifts of generics and TS code in general. If we encouraged folks to use our generics, they'd break in a minor easily, even past v1.

Our goal is to create APIs that handle this usecase without the need of generics passing of any kind.

To that end, please review the APIs outlined in this newest PR, which I believe should handle the usage you need:

#1179

[deniskabana]

Thank you for your response @crutchcorn. This does not address the lacking JS representation of any data during compile-time.

This code is from your PR's description:

// /src/features/people/shared-form.ts, to be used across `people` features
const formOpts = formOptions({
  defaultValues: {
    firstName: 'John',
    lastName: 'Doe',
  },
})

We only have TS interfaces, no objects that would represent them run-time. These are constructed from the form itself the first time it is submitted. Until then, all we have is a TS interface we import. This makes it close to impossible to stick with @tanstack/form-react for multiple projects I am working on.

---

In 0.42.x, this is what our code looked like:

const Test = () => {
  const form = useForm<IFormSchema>({ onSubmit: console.log });

  return (
    <FormInputText /* custom abstraction */
      form={form}
      name="locales.default" /* TS suggestions */
      label="Default language"
      minLength={2}
      maxLength={2}
      required
    />
  )
};

[crutchcorn]

@deniskabana I'm not following why the following does not work:

const formOpts = formOptions({ defaultValues: { } as SomeInterfaceHere })

It works at compile time just fine.

[deniskabana]

@crutchcorn This causes unexpected failures that TS does not prevent:

  const form = useForm({
    defaultValues: {} as MySchema,
  });

  // Following code is valid TS, no errors

  const defaultLocale = useStore(form.store, (state) => state.values.locales.default);
  // [JS] TypeError: Cannot read properties of undefined (reading 'default')
  console.log(defaultLocale.length);
  // [JS] TypeError: Cannot read properties of undefined (reading 'length')

EDIT: This causes the TS to not be useful at all since it never flagged the code as incorrect.

[crutchcorn]

That's a bug, and one I'm rather surprised to see given how extensive our type tests are for this usecase.

Can you create a minimal repro on an issue and I'll prioritize a fix/response?

[deniskabana]

I'm not sure what the bug is here, as it is an expected TypeScript behavior with typecasting. Try this for yourself in TS:

(({}) as { firstName: string }).firstName.trim();
// [TS] ✅
// [JS] TypeError: Cannot read properties of undefined (reading 'trim')

({}).firstName.trim();
// [TS] Cannot find name 'firstName'.
// [JS] TypeError: Cannot read properties of undefined (reading 'trim')

This is why I keep pushing against your notion of not needing the generic types - typecasting foregoes any information about the shape of the object by design.

Edit: CC @crutchcorn

[crutchcorn]

I'm fundamentally not understanding how a generic type fixes this.

Let's assume that you pass a generic as it was before and we """"fixed"""" this behavior differencial:

useForm<MySchema>();

vs

useForm({defaultValues: {} as MySchema});

Both of these values will behave identically at runtime:

// Following code is valid TS, no errors

const defaultLocale = useStore(form.store, (state) => state.values.locales.default);
// [JS] TypeError: Cannot read properties of undefined (reading 'default')
console.log(defaultLocale.length);
// [JS] TypeError: Cannot read properties of undefined (reading 'length')

The behavior is exactly the same at both compile time and runtime alike. The only difference is in DX and one of our core philosophies (even from the start) has been to avoid anyone passing anything to our generics.

---

Even from day 1 we always guided people away from using generics in our Discord, issues, and forums. For a short while, we had a few docs/test items that used this API, but they were errant and removed as soon as we caught them during reviews.

Again, if someone is able to make it such that you can pass a single generic and have all the inferencing still work we'd love a PR.

That said, it's not currently possible in TypeScript - it's an inherent limitation on the language:

function test<TExplicit = never, TInfer = undefined>(val: TInfer) {
    return val;
}

const val = test(123);
//      ^? `123`

const castVal = test<never>(123);
//                          ^? Argument of type '123' is not assignable to parameter of type 'undefined'.(2345)

And again, it's incredibly brittle in case we ever add a mandatory type in the future.

---

I understand y'all are frustrated, I empathize with this. Could I go back in time and make our boundaries and guidance more clear I would. Hindsight is 20/20. But for 99% of our users, I strongly believe this is the right way to go.