How to extend the useForm hook?

[DoubleDebug]

Hello, I'm new to the @tanstack/react-form library and I need help with customizing the useForm hook.

What exactly do I want?

Let's say I have a Zod schema for each of my forms:

const PersonSchema = z.object({
  firstName: z.string(),
  lastName: z.string()
};
type Person = z.infer<typeof PersonSchema>;

Instead of writing this:

const form = useForm({
  defaultValues: {
    firstName: '',
    lastName: ''
  } as Person,
  validators: {
    onChange: personSchema
  }
});

... I want to write this:

const form = useMyForm({
  schema: PersonSchema,
});

... and get the same result.

Why do I want this?

I have tens of forms in my application and I want to reduce boilerplate as much as possible. I also want to have some "global" control over the useForm hook in case I want to change the behavior for ALL forms in my application. This is why I decided to make a wrapper for the useForm hook.

To be clear, I don't want to reuse a part of my FormOptions (as suggested here). I want to slightly modify how the useForm behaves across my entire app.

What I tried

import { z } from 'zod';
import { getZodDefaults } from '@/utils/zod';
import { FormOptions, useForm } from '@tanstack/react-form';

interface Options<Schema extends z.ZodRawShape> extends FormOptions {
  schema: z.ZodObject<Schema>;
}

export function useMyForm<Schema extends z.ZodRawShape>(options: Options<Schema>) {
  return useForm({
    ...options,
    defaultValues: getZodDefaults(options.schema) as z.infer<typeof options.schema>,
    validators: {
      ...options.validators,
      onChange: options.schema,
    },
  });
}

There are 2 problems with my implementation.

1. This is not valid Typescript, because FormOptions is a generic type and it requires 10 type arguments. 🤯
2. The resulting type of my hook is:

const form: ReactFormExtendedApi<{
    [x: string]: any;
}>

This means that it doesn't work and it doesn't correctly inherit the Person type.

Am I going in the wrong direction?

I read in the docs that

You should never need to pass a generic or use an internal type when leveraging TanStack Form.

This is partly the reason why I'm making this discussion. Is there a smarter way to do this?

[LeCarbonator]

The generic parameters are for the validation. The formOptions would be the way to go about it, but if you really want to extend the base useForm, here's some things to note:

• type defaultValues as z.input<typeof options.schema> since that's the standard schema type tanstack will check for
• the 10 generics are for the passed validation objects and the onSubmit meta. Since you hardcode the validation object, you can probably preset most of the generics (more generics could be added in the future, so be careful)
• You'll want to omit defaultValues and validators from your extension of FormOptions, as they will be overwritten and most likely break the typing.

[LeCarbonator]

Personally, I wouldn't abstract to this level for a couple lines. Yes, you have tens of forms, but you hide the form's behaviour behind a second hook which may lead to undesired behaviour. In your snippet, you overwrote defaultValues, but you could've still passed it to your hook.

• What if your data comes in from somewhere else and you wanted to set that data? suddenly you have issues where your form doesn't work as expected.
• What if your zod schema is a union? which default value will it use? how do you control which one of the unions it will use first? You'll have to dig into the utils function to find that out, just to figure out how your schema will handle it.
• Is it global control if the hook is generic and you can extend it individually anyways? The only true thing it overwrites is onChange and defaultValues, the rest can still be changed to anything on a per use basis.

Here's your example of extending the form:

const form = useSchemaForm({
   schema: createProfileSchema,
   validators: {
       onSubmitAsync: async ({ value }) => 'Do something'
   }
})

If you hadn't 'removed boilerplate', it would be:

// why is 'getZodDefaults' not already typed as z.input<createProfileSchema>? Is it actually the input it gets?
const defaultValues = getZodDefaults(createProfileSchema) as z.input<createProfileSchema>
const form = useForm({
   defaultValues,
   validators: {
       onSubmitAsync: async ({ value }) => 'Do something',
       onChange: createProfileSchema
   }
})

6 lines vs. 8. Except with the latter, I now know how the defaultValues came to be and what the form's behaviour is. I can adjust future versions in different forms without breaking existing forms since they share no formOptions.

It's up to you. These are just my thoughts on the matter.

[DoubleDebug]

@LeCarbonator Hey, thanks for the reply.

You actually helped me get to the answer. Changing the return type of my getZodDefaults function to z.input<typeof options.schema> solved my problem and the type inference started woking. This makes me think that this issue was more related to zod than react-form - sorry about that! 😅

What I ended up doing is customizing the formOptions() function instead of useForm. Here's the code:

type CustomFormOptions<
  Schema extends z.ZodRawShape,
  A = z.input<z.ZodObject<Schema>>,
  B extends FormValidateOrFn<A> = FormValidateOrFn<A>,
  C extends FormValidateOrFn<A> = FormValidateOrFn<A>,
  D extends FormValidateOrFn<A> = FormValidateOrFn<A>,
  E extends FormValidateOrFn<A> = FormValidateOrFn<A>,
  F extends FormValidateOrFn<A> = FormValidateOrFn<A>,
  G extends FormValidateOrFn<A> = FormValidateOrFn<A>,
  H extends FormValidateOrFn<A> = FormValidateOrFn<A>,
  I extends FormValidateOrFn<A> = FormValidateOrFn<A>,
> = Omit<FormOptions<A, B, C, D, E, F, G, H, I>, 'defaultValues'> & {
  schema: z.ZodObject<Schema>;
  defaultValues?: Partial<z.input<z.ZodObject<Schema>>>;
};

export function createFormOptions<Schema extends z.ZodRawShape>(options: CustomFormOptions<Schema>) {
  return {
    ...options,
    defaultValues: {
      ...getFormDefaults(options.schema),
      ...options.defaultValues,
    },
    validators: {
      onChange: options.schema,
      ...options.validators,
    },
  };
}

Usage:

import { z } fom 'zod';
import { useForm } from '@tanstack/react-form';
import { createFormOptions } from '@/utils/form';

const PersonSchema = z.object({
  firstName: z.string(),
  lastName: z.string()
};

const form1Options = createFormOptions({ schema: PersonSchema });

const Form = () => {
  const form = useForm(form1Options);
  // resulting type:
  // const form: ReactFormExtendedApi<{
  //     firstName: string;
  //     lastName: string;
  // }>

  return <div>...</div>
}

This allows me to:

• reduce boilerplate
• have "global" control over the default values of all my forms
• override this default behavior (if needed)
• maintain the cool type inference of @tanstack/react-form

I understand that this solution:

• goes against the philosophy of "never passing a generic or using an internal type",
• might introduce problems in the future in case the generic types change.