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

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

About this issue

  • Original URL
  • State: closed
  • Created 2 years ago
  • Reactions: 6
  • Comments: 26 (11 by maintainers)

Most upvoted comments

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
})

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

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

It works at compile time just fine.

Hey @craigbehnke , I can see you’re frustrated. Here’s the deal: I’m frustrated too. Your tone isn’t appropriate and frankly your feedback is months late.

Please feel free to reopen a discussion elsewhere with a more inquisitive and polite response and I might reply.

Until then, please consider the folks on the maintaining side.

Have a good day!

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

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.

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.

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

This can be avoided by using satisfies. E.g. defaultValues: { name: {} satisfies Name as Name }

Haven’t followed this discussion closely and might be a little off here, doesn’t something like what I’m doing here work?

FormState<
	TFormData,
	FormValidateOrFn<TFormData> | undefined,
	FormValidateOrFn<TFormData> | undefined,
	FormAsyncValidateOrFn<TFormData> | undefined,
	FormValidateOrFn<TFormData> | undefined,
	FormAsyncValidateOrFn<TFormData> | undefined,
	FormValidateOrFn<TFormData> | undefined,
	FormAsyncValidateOrFn<TFormData> | undefined,
	FormAsyncValidateOrFn<TFormData> | undefined
>;

@craigbehnke I’m both surprised and grateful that you’ve come back to this issue in such a positive light. I do appreciate it ✨ I’m also sorry you’ve gotten sudden work on your plate - that’s genuinely never fun.

So yeah, here’s the reason for the 9 generics: They’re inferring things from the code you’ll likely want to keep with any kind of wrapper around useForm that you’d make. This includes:

  • Types of onChange/onBlur/et al errors
  • defaultValues as FormData
  • Likely more generics added in future releases for other features

The way I’d work around this actually pretty heavily depends on what your goals are with useCustomForm. What are you looking to extend from form with?

I actually have an idea for how to add useCustomForm more easily, but worry that we may have already solved this with useAppForm and createFormHook APIs:

https://tanstack.com/form/latest/docs/framework/react/guides/form-composition

Could you look through those docs real quick and if they don’t suit your needs let me know what you’re aiming to do?

BTW, as a quick “let’s unblock Craig ASAP”, you can just cast the other 9 generics as any and allow for implicit returns:

import {useForm, FormOptions as TanStackFormOptions} from "@tanstack/react-form";

interface InputProperties<TData> extends TanStackFormOptions<TData, any, any, any, any, any, any, any, any> {
    // Extra options here
}

// Infer the return type
export function useCustomForm<TData>(properties: InputProperties<TData>) {
    const form = useForm(properties)

    // Extra code here

    return {
        ...form,
        // Extra return values
   }
} 

Just be aware that this is a brittle solution that we can’t respect as part of semantic versioning (we don’t cover generics types under semver) so let’s try to figure out a long-term solution together as well 😃

@crutchcorn On further reflection, I apologize for any perceived slight against you or the project. My frustration is with the work suddenly on my plate, not you, and I recognize that you are likely working on this project on a volunteer basis.

With that in mind, I would greatly appreciate any input you may have into whether there is a migration path from the custom hook I outlined above to the current best practice for using the library. How can we get a fully typed form object out of the useForm hook (and a fully typed input object) without manually setting the 8-9 new generic types, which you have already said is not the intended use case?

@crutchcorn I’m not sure what in my comment warranted your snarky response.

Previously valid behaviors using the library broke without a workaround or migration path – that’s not something I’m used to in any tanstack library, and it frankly surprised me.

I went over what I have been doing up until now that was impacted by the change.

I highlighted that this is not an isolated issue, but affects many people that have not been able to update.

I then outlined what I wanted to be able to do and asked whether it was possible to a thread that, to be candid, was already discussing workarounds for the issue.

There was no language, and I did not personally insult you.

Please forgive my frustration that I had to deal with a breaking change raised by an automated branch on a Sunday.

I just tried to upgrade, and was blown away by this change. (Not in a good way)

We have a custom react hook that wraps the tanstack useForm hook and then adds some additional functions and a FormWrapper component to the final returned type. This lets us centralize all form boilerplate into one hook that can then be imported into a bunch of different forms within the app.

This change makes that untenable, since my understanding is that we would have to add all the new generics to the hook itself and then manually set those generics at every call site.

I don’t want to have to do this (it would take a long time to achieve, if it is even possible), and so I checked the npm registry for the last version of the library before this change, and it seems that version is the 3rd most popular over the past week.

Version Downloads (Last 7 Days) Published
1.3.0 31,548 23 days ago
1.6.3 24,270 8 days ago
0.42.1 17,896 2 months ago
0.33.0 14,636 7 months ago
1.3.1 7,658 18 days ago
1.3.3 5,433 15 days ago

Evidently a lot of people, myself included, do not want to deal with the headaches this change introduces. Is there a way to make this change less absurd? Put another way specifically for my use case, is there a way to wrap the useForm hook in another hook and have total type safety, just like before?

Something like:


interface InputProperties<...> extends TanStackFormOptions<...> {
    // Extra options here
}

interface ReturnValues<...> extends TanStackFormApi<...> {
    // Extra returned values here
}

export function useCustomForm<...>(properties: InputProperties<...>): ReturnValues<...> {
    const form = useForm(properties)
    
    // Extra code here

    return {
        ...form,
        // Extra return values
    }
}

Is that possible right now, and if not, what would need to change?

We use ReturnType of our custom form hook initializer function as the form’s type, this works if you don’t require any dynamic default values and validators.

const { useAppForm } = createFormHook({ ... });

export function useMyForm() {
  return useAppForm({ ... });
}

export type MyForm = ReturnType<typeof useMyForm>;

// Use as prop or function parameter without any issues:
interface MyProps {
  form: MyForm;
}

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.