feat: zod v4 support #768 #776

alexcraviotto · 2025-05-31T12:52:10Z

Support for Zod v4 with `zodResolverV4`

This PR adds support for the new version of Zod (v4) by introducing a new resolver: zodResolverV4. This allows users to work with schemas written using the latest version of Zod while maintaining compatibility with older implementations.

To ensure backward compatibility, the original zodResolver has not been removed or modified.

Due to issues related to tests in typeschema.ts, I’ve temporarily installed two separate versions of Zod (zod and zod-v4) to avoid breaking existing functionality. Ideally, in the future, it would be great to update those parts to also use the latest version of Zod.

Usage

Using the new resolver is simple. You just need to import and use zodResolverV4 like so:

const { control, handleSubmit, formState: { errors } } = useForm<User>({
  resolver: zodResolverV4(UserSchema),
  defaultValues: {
    name: '',
    device: {
      platform: 'ios',
      versions: []
    }
  }
});

Big thanks to @hukpo for mentioning this solution in Issue #768 🙌

Copilot

Pull Request Overview

Adds support for Zod v4 by introducing a new zodResolverV4 and preserving the existing resolver.

Introduces zodv4.ts with a resolver that uses a Zod v4 alias
Updates index.ts to export both zodResolver and zodResolverV4
Adjusts package.json to install an aliased Zod v4 and bumps the existing Zod version
Cleans up duplicate imports in typebox tests

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

File	Description
zod/src/zodv4.ts	Implements `zodResolverV4` using the aliased Zod
zod/src/index.ts	Exports original resolver and adds the v4 alias
typebox/src/tests/typebox.ts	Removes duplicate imports in tests
package.json	Bumps Zod dev dep and adds `zod-v4` alias

Copilot · 2025-06-01T00:18:46Z

zod/src/zodv4.ts

+  ResolverSuccess,
+  appendErrors,
+} from 'react-hook-form';
+import { ZodError, z } from 'zod-v4/v4';


The import path 'zod-v4/v4' is unusual and may not resolve correctly. Consider importing directly from the aliased package (e.g. import { ZodError, z } from 'zod-v4';).

Suggested change

import { ZodError, z } from 'zod-v4/v4';

import { ZodError, z } from 'zod-v4';

It needs to be done that way to work.

Copilot · 2025-06-01T00:18:47Z

zod/src/index.ts

@@ -1 +1,2 @@
-export * from './zod';
+export { zodResolver } from './zod';


Replacing export * with named exports removes other exports from ./zod. If consumers rely on additional types or utilities, re-export them too or restore export *.

We do it this way to be able to export both resolvers of both versions.

Copilot · 2025-06-01T00:18:47Z

package.json

  },
  "peerDependencies": {
    "react-hook-form": "^7.55.0"
  },
  "dependencies": {
-    "@standard-schema/utils": "^0.3.0"
+    "@standard-schema/utils": "^0.3.0",
+    "zod-v4": "npm:zod@^3.25.0"


The alias zod-v4 points to zod@^3.25.0, which is still v3. To install Zod v4, update this alias to a ^4.x version.

Suggested change

"zod-v4": "npm:zod@^3.25.0"

"zod-v4": "npm:zod@^4.x"

colinhacks · 2025-06-01T08:10:59Z

package.json

  },
  "peerDependencies": {
    "react-hook-form": "^7.55.0"
  },
  "dependencies": {
-    "@standard-schema/utils": "^0.3.0"
+    "@standard-schema/utils": "^0.3.0",
+    "zod-v4": "npm:zod@^3.25.0"


This should be a dev dependency, like all the other schema libraries

colinhacks · 2025-06-01T08:13:59Z

zod/src/zodv4.ts

+/**
+ * Creates a resolver function for react-hook-form that validates form data using a Zod schema
+ * @param {z.ZodSchema<Input>} schema - The Zod schema used to validate the form data
+ * @param {Partial<z.ParseParams>} [schemaOptions] - Optional configuration options for Zod parsing


Update

Suggested change

* @param {Partial<z.ParseParams>} [schemaOptions] - Optional configuration options for Zod parsing

* @param {z.core.ParseContext<z.core.$ZodIssue>} [schemaOptions] - Optional configuration options for Zod parsing

colinhacks · 2025-06-01T08:16:55Z

zod/src/zodv4.ts

+export function zodResolver<Input extends FieldValues, Context, Output>(
+  schema: z.ZodSchema<Output, Input>,
+  schemaOptions?: Partial<z.core.ParseContext<z.core.$ZodIssue>>,
+  resolverOptions?: {
+    mode?: 'async' | 'sync';
+    raw?: false;
+  },
+): Resolver<Input, Context, Output>;
+
+export function zodResolver<Input extends FieldValues, Context, Output>(
+  schema: z.ZodSchema<Output, Input>,
+  schemaOptions: Partial<z.core.ParseContext<z.core.$ZodIssue>> | undefined,
+  resolverOptions: {
+    mode?: 'async' | 'sync';
+    raw: true;
+  },
+): Resolver<Input, Context, Input>;


Why are these split into separate overloads? Odd considering their return types are identical.

I believe the reason is that

in the raw: true case, the output type is Resolver<Input, Context, Input>—the original input is returned

whereas in the opposite case (resolverOptions.raw is omitted or false) then the output type is Resolver<Input, Context, Output>.

I suggested the overload in #753 (comment), because I believe without it it’s not possible to express this kind of “conditional return type”

colinhacks · 2025-06-01T08:22:09Z

zod/src/zodv4.ts

+  ResolverSuccess,
+  appendErrors,
+} from 'react-hook-form';
+import { ZodError, z } from 'zod-v4/v4';


Tooling like this should only be importing from "/v4/core". This way you can support Zod (Regular) and Zod Mini schemas simultaneously. See https://zod.dev/library-authors

colinhacks · 2025-06-01T08:22:32Z

zod/src/zodv4.ts

+): Resolver<Input, Context, Output>;
+
+export function zodResolver<Input extends FieldValues, Context, Output>(
+  schema: z.ZodSchema<Output, Input>,


This should be z.core.$ZodType to allow for Zod Mini schemas

colinhacks · 2025-06-01T08:23:34Z

zod/src/zodv4.ts

+  return async (values: Input, _, options) => {
+    try {
+      const data = await schema[
+        resolverOptions.mode === 'sync' ? 'parse' : 'parseAsync'


After switching over to z.core.$ZodType, you'll need to use the top level z.parse and z.parseAsync functions here. The $ZodType base class has no methods.

alexcraviotto · 2025-06-01T09:38:41Z

Thanks for the review @colinhacks 🙌

I've uploaded the changes in the last commit.

bluebill1049 · 2025-06-01T10:09:28Z

thanks @colinhacks for the review 🙏

CHC383 · 2025-06-02T21:27:00Z

bun.lock

@@ -5,6 +5,7 @@
      "name": "@hookform/resolvers",
      "dependencies": {
        "@standard-schema/utils": "^0.3.0",
+        "zod-v4": "npm:zod@^3.25.0",


The lock file also needs to be updated after moving zod-v4 to devDependencies

The lock file also needs to be updated after moving zod-v4 to devDependencies

Shouldn't zod-v4 be under devDependencies? Only the standard schema is included as a dependency.

CHC383 · 2025-06-02T21:32:27Z

zod/src/zodv4.ts

+  ResolverSuccess,
+  appendErrors,
+} from 'react-hook-form';
+import { ZodError } from 'zod-v4/v4';


I think for v4-mini compatibility, the code should use core.$ZodError instead.

https://zod.dev/packages/core?id=errors#errors

controversial · 2025-06-02T22:21:49Z

zod/src/zodv4.ts

+export function zodResolver<Input extends FieldValues, Context, Output>(
+  schema: core.$ZodType<Output, Input>,
+  schemaOptions?: Partial<core.ParseContext<core.$ZodIssue>>,
+  resolverOptions?: {
+    mode?: 'async' | 'sync';
+    raw?: false;
+  },
+): Resolver<Input, Context, Output>;


it seems like the overload for raw: true was incorrectly removed, which breaks the types when this option is passed @alexcraviotto

see #776 (comment)

ByteEVM · 2025-06-03T08:18:47Z

bun.lock

@@ -54,7 +55,7 @@
        "vite-tsconfig-paths": "^5.1.4",
        "vitest": "^3.0.9",
        "yup": "^1.6.1",
-        "zod": "^3.24.2",
+        "zod": "3.24.4",


Fixing @CHC383 's suggestion by moving zod-v4 to devDependencies

Suggested change

"zod": "3.24.4",

"zod": "3.24.4",

"zod-v4": "npm:zod@^3.25.0",

jorisre · 2025-06-07T13:36:13Z

Thanks a lot @alexcraviotto for your contribution. Closing in favor of #777

alexcraviotto added 2 commits May 31, 2025 14:46

feat: zod v4 support

ba6a6f0

fix: zod version

ac63b9c

bluebill1049 requested review from jorisre and Copilot June 1, 2025 00:17

Copilot AI reviewed Jun 1, 2025

View reviewed changes

colinhacks reviewed Jun 1, 2025

View reviewed changes

fix: align zod integration with library authoring best practices

8d9e1bc

CHC383 reviewed Jun 2, 2025

View reviewed changes

controversial reviewed Jun 2, 2025

View reviewed changes

ByteEVM reviewed Jun 3, 2025

View reviewed changes

This was referenced Jun 4, 2025

Type instantiation is excessively deep and possibly infinite" when using Zod with React Hook Form and @hookform/resolvers colinhacks/zod#4474

Closed

feat: support Zod 4 #777

Merged

jorisre closed this Jun 7, 2025

	import { ZodError, z } from 'zod-v4/v4';
	import { ZodError, z } from 'zod-v4';

		@@ -1 +1,2 @@
		export * from './zod';
		export { zodResolver } from './zod';

	* @param {Partial<z.ParseParams>} [schemaOptions] - Optional configuration options for Zod parsing
	* @param {z.core.ParseContext<z.core.$ZodIssue>} [schemaOptions] - Optional configuration options for Zod parsing

	"zod": "3.24.4",
	"zod": "3.24.4",
	"zod-v4": "npm:zod@^3.25.0",

Uh oh!

feat: zod v4 support #768 #776

feat: zod v4 support #768 #776

Uh oh!

Conversation

alexcraviotto commented May 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Support for Zod v4 with zodResolverV4

Usage

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Jun 1, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jun 1, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jun 1, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alexcraviotto commented Jun 1, 2025

Uh oh!

bluebill1049 commented Jun 1, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jorisre commented Jun 7, 2025

Uh oh!

Uh oh!

alexcraviotto commented May 31, 2025 •

edited

Loading

Support for Zod v4 with `zodResolverV4`