Type inference issues with zod v4 and useForm generic wrapper

[Zoe7]

Background

In an application I work on, we have a utility hook useZodForm that wraps useForm with zodResolver to simplify form setup with zod validation and get the correct type inference for the form methods based on the zod schema provided.

This worked perfectly in zod v3:

import { zodResolver } from '@hookform/resolvers/zod';
import { useForm, UseFormProps, FieldValues } from 'react-hook-form';
import type z from 'zod';

export const useZodForm = <
  TSchema extends z.Schema,
  TFieldValues extends FieldValues = z.infer<TSchema>,
>(
  props: {
    schema: TSchema;
  } & Omit<UseFormProps<z.infer<TSchema>>, 'resolver'>,
) => {
  const { schema, ...rest } = props;
  return useForm<TFieldValues>({
    resolver: zodResolver(schema),
    ...rest,
  });
};

In zod v3, z.infer<TSchema> when TSchema extends z.Schema would infer to any, which was compatible with FieldValues which evaluates to Record<string, any>.

The Problem

After upgrading to zod v4, z.Schema is now defined as ZodType<unknown, unknown, ...>, which means when you constrain a generic type parameter as TSchema extends z.ZodType, TypeScript can only infer unknown for z.infer<TSchema>, z.input<TSchema>, and z.output<TSchema>.

for example:

export const useZodForm = <TSchema extends z.Schema>(
  props: { schema: TSchema } & Omit<
    UseFormProps<z.input<TSchema>, any, z.output<TSchema>>,
    'resolver'
  >,
) => {
  // TypeScript sees z.input<TSchema> as 'unknown'
  return useForm<z.input<TSchema>, any, z.output<TSchema>>({
    resolver: zodResolver(props.schema),
    ...props,
  });
   // ❌ Error: Type 'unknown' does not satisfy constraint 'FieldValues'
};

I tried using z.Schema<any, any> as a constraint, to bring us back closer to the old, zod v3 behavior. This works great for type inference:

// This pattern works great for type inference
export const useZodForm = <TSchema extends z.Schema<any, any>>(
  schema: TSchema,
  options?: Omit<
    UseFormProps<z.input<TSchema>, any, z.output<TSchema>>,
    'resolver'
  >,
) => {
  // ✅ TypeScript infers z.input<TSchema> and z.output<TSchema> to `any` which satisfies the constraint 'FieldValues'
  return useForm<z.input<TSchema>, any, z.output<TSchema>>({
    resolver: zodResolver(schema),
    ...options,
  });
};

The problem is that when we try to use it in practice, Typescript tries to evaluate whether the schema we pass in structurally matches ZodType<any, any>, which it does not and things fail:

const formSchema = z.object({
  isBoolean: z.boolean(),
});
// formSchema is of type: ZodObject<{ isBoolean: ... }, ...>

useZodForm(formSchema);
// ❌ Error: Type 'ZodObject<...>' is missing properties from type 'ZodType<any, any, ...>'

Question

I'm running a bit out of ideas on how to deal with this in a way that does not involve type casting or @ts-expect-error 😅
Anyone has figured out the right way to deal with this yet?

---

Versions used for info:

• zod: 4.1.13
• react-hook-form: 7.66.0
• @hookform/resolvers: 5.2.2
• TypeScript: 5.9.3

[ismaildasci]

zod v4 changed how Schema type works. the fix is to use ZodTypeAny instead of Schema:

import { zodResolver } from "@hookform/resolvers/zod";
import { useForm, UseFormProps, FieldValues } from "react-hook-form";
import { z, ZodTypeAny } from "zod";

export const useZodForm = <
  TSchema extends ZodTypeAny,
  TFieldValues extends FieldValues = z.infer<TSchema>,
>(
  props: {
    schema: TSchema;
  } & Omit<UseFormProps<z.infer<TSchema>>, "resolver">,
) => {
  const { schema, ...rest } = props;
  return useForm<TFieldValues>({
    resolver: zodResolver(schema),
    ...rest,
  });
};

ZodTypeAny is ZodType<any, any, any> which gives proper inference.

alternatively you can add type assertion:

export const useZodForm = <TSchema extends z.ZodType>(
  schema: TSchema,
  options?: Omit<UseFormProps<z.infer<TSchema>>, "resolver">,
) => {
  return useForm({
    resolver: zodResolver(schema),
    ...options,
  } as UseFormProps<z.infer<TSchema>>);
};

the ZodTypeAny approach is cleaner and works without casting

[sunnypatell]

why this breaks

the root cause is a change in how zod's base type generics default.

zod v3:

// ZodType defaults all generics to `any`
abstract class ZodType<Output = any, Def extends ZodTypeDef = ZodTypeDef, Input = Output> { ... }

// z.Schema was just an alias
export { ZodType as Schema, ZodType as ZodSchema };

// ZodTypeAny = ZodType<any, any, any>
export type ZodTypeAny = ZodType<any, any, any>;

// inference used direct property access
export type output<T extends ZodType<any, any, any>> = T["_output"];

zod v4:

// ZodType defaults all generics to `unknown`
interface ZodType<out Output = unknown, out Input = unknown, out Internals extends ...> { ... }

// Schema, ZodSchema, ZodTypeAny are all deprecated aliases for ZodType
export type {
  ZodType as ZodTypeAny,  // deprecated, just `ZodType` now
  ZodType as ZodSchema,   // deprecated
  ZodType as Schema,      // deprecated
};

// inference uses conditional types against `_zod` internals
export type output<T> = T extends { _zod: { output: any } } ? T["_zod"]["output"] : unknown;

so when you write TSchema extends z.Schema (or z.ZodType) in v4, typescript sees the upper bound as ZodType<unknown, unknown>. the conditional type helper z.infer<TSchema> resolves T["_zod"]["output"] against that upper bound and gets unknown. since unknown doesn't satisfy FieldValues (Record<string, any>), useForm rejects it.

the important thing to understand is that ZodTypeAny is not ZodType<any, any, any> anymore in v4. it's just an alias for ZodType which still defaults to <unknown, unknown>. so the existing answer suggesting ZodTypeAny won't actually fix the root issue (it's the same type).

why z.Schema<any, any> fails structurally

you already found that z.Schema<any, any> (= ZodType<any, any>) fixes the inference issue because it shifts the upper bound to any. but then concrete schemas like ZodObject<...> fail to structurally match.

this happens because the classic ZodType interface in v4 is massive. it defines parse, safeParse, check, brand, clone, register, toJSONSchema, encoding/decoding methods, and more. when typescript checks whether your ZodObject<{ isBoolean: ... }> structurally matches ZodType<any, any>, it has to verify compatibility across all of those members with the specific Internals generic parameter, and that structural check can fail on complex instantiations.

the fix: use z.core.$ZodType instead

zod v4 exposes a much leaner base interface at z.core.$ZodType (library authors docs). it only requires two structural properties:

interface $ZodType<O = unknown, I = unknown> {
  _zod: $ZodTypeInternals<O, I>;
  "~standard": StandardSchemaV1.Props<...>;
}

every zod v4 schema satisfies this interface, and it's what @hookform/resolvers uses internally for its zod v4 overloads. by constraining your generic to z.core.$ZodType<any, any>, you get:

1. correct upper bound - any means z.infer<TSchema> resolves to any at the constraint level, satisfying FieldValues
2. structural compatibility - the interface is minimal enough that every concrete schema matches
3. preserved inference - when you actually call the hook with a concrete schema, typescript narrows TSchema to the specific type and z.infer<TSchema> gives you the real inferred type

import { zodResolver } from '@hookform/resolvers/zod';
import { useForm, type UseFormProps, type FieldValues } from 'react-hook-form';
import type z from 'zod';
import type { $ZodType } from 'zod/v4/core';

export const useZodForm = <
  TSchema extends $ZodType<any, any>,
  TFieldValues extends FieldValues = z.infer<TSchema>,
>(
  props: {
    schema: TSchema;
  } & Omit<UseFormProps<z.infer<TSchema>>, 'resolver'>,
) => {
  const { schema, ...rest } = props;
  return useForm<TFieldValues>({
    resolver: zodResolver(schema),
    ...rest,
  });
};

usage stays the same:

const formSchema = z.object({
  isBoolean: z.boolean(),
});

const form = useZodForm({ schema: formSchema });
// form is UseFormReturn<{ isBoolean: boolean }>

if you don't want to import from zod/v4/core directly, you can access it through the z.core namespace:

import type z from 'zod';

export const useZodForm = <
  TSchema extends z.core.$ZodType<any, any>,
  TFieldValues extends FieldValues = z.infer<TSchema>,
>( ... ) => { ... };

alternative: no extra import, type-level cast

if you want to avoid the zod/v4/core import entirely (maybe you're writing code that should stay version-agnostic), you can use a structural constraint inline:

export const useZodForm = <
  TSchema extends { _zod: { output: any; input: any } },
  TFieldValues extends FieldValues = z.output<TSchema>,
>(
  props: {
    schema: TSchema;
  } & Omit<UseFormProps<z.output<TSchema>>, 'resolver'>,
) => {
  const { schema, ...rest } = props;
  return useForm<TFieldValues>({
    resolver: zodResolver(schema as any),
    ...rest,
  });
};

this works because z.output<T> / z.infer<T> in v4 is defined as a conditional type:

type output<T> = T extends { _zod: { output: any } } ? T["_zod"]["output"] : unknown;

so as long as your constraint tells typescript that _zod.output exists and is any, inference works. the tradeoff is the as any on zodResolver(schema) since it won't recognize your structural type.

summary

constraint	inference	structural match	recommendation
z.Schema / z.ZodType (default)	unknown	yes	won't work with FieldValues
z.Schema<any, any>	any	often fails on complex schemas	fragile
z.core.$ZodType<any, any>	any (then narrows on usage)	yes (minimal interface)	recommended
{ _zod: { output: any; input: any } }	works via conditional	yes	works but needs as any on zodResolver

relevant links:

• zod v4 library authors guide - explains z.core.$ZodType for library authors
• zodResolver source - how @hookform/resolvers handles both v3 and v4
• zod v4 core types - output<T> conditional type definition