@hookform/resolvers

@hookform/resolvers is the official bridge between React Hook Form and the schema-validation ecosystem. Rather than writing custom validation logic by hand, you write your schema once in the validation library of your choice and pass a matching resolver — zodResolver, yupResolver, joiResolver, valibotResolver, and more — into useForm. Each resolver normalizes that library’s parse/validate output into React Hook Form’s internal FieldErrors shape, including nested paths, field arrays, and native browser validation.

The package is a monorepo of ~20 small, independently-published sub-packages (one per validation library) that all share the same two core utilities — toNestErrors and validateFieldsNatively — so behavior is consistent regardless of which schema library a team standardizes on. This makes it the default choice for TypeScript-first form validation in the React ecosystem, especially for teams already using Zod, Yup, or Valibot elsewhere in their codebase.

What You Get

• One resolver function per supported validation library (zodResolver, yupResolver, joiResolver, valibotResolver, arktypeResolver, ajvResolver, and 15+ others), each importable from its own sub-path (@hookform/resolvers/zod, @hookform/resolvers/yup, etc.) to keep bundles small
• Automatic error-shape translation via the shared toNestErrors utility, converting each library’s native error format into React Hook Form’s nested FieldErrors structure, including array and object paths
• Built-in support for native HTML5 validation via validateFieldsNatively, which calls setCustomValidity/reportValidity on form fields when shouldUseNativeValidation is enabled
• TypeScript type inference end-to-end — most resolvers infer both input and output types directly from the schema, so useForm<Input, Context, Output>() reflects transforms and coercions declared in the schema
• Sync and async validation modes plus a raw option to return the original form values instead of the schema-parsed/coerced output

Common Use Cases

• Validating a signup or checkout form where the schema (e.g. Zod) is already shared between client and server for consistent validation rules
• Migrating a codebase from one schema library to another (e.g. Yup to Zod) without rewriting form-handling logic, since only the resolver import changes
• Building design-system form components that need to support whichever validation library a consuming team already uses, by accepting any @hookform/resolvers-compatible resolver as a prop
• Enforcing native browser validation UI (tooltips, :invalid styling) while still driving validation logic from a typed schema instead of raw HTML validation attributes

Under The Hood

Architecture The repo is a monorepo of ~20 sibling packages (zod/, yup/, joi/, valibot/, ajv/, arktype/, etc.), each with its own src/, tests/, package.json, and export map, plus a root src/ containing the two utilities every resolver shares: toNestErrors.ts and validateFieldsNatively.ts. A resolver’s job is narrow and consistent across libraries: call the target library’s parse/validate function, and on failure map its native error shape into React Hook Form’s FieldErrors via toNestErrors, which walks each error path with react-hook-form’s own get/set helpers so nested objects and field-array roots resolve identically regardless of which schema library produced the error. config/node-13-exports.js post-processes the build output to copy each sub-package’s .module.js to .mjs for older Node resolution, and check-export-map (postbuild) verifies every sub-path in package.json’s exports map actually resolves to real build artifacts. Tech Stack Written entirely in TypeScript (98.7% of the codebase) and built with microbundle, producing ESM (.mjs), CJS (.js), and UMD bundles per sub-package so each resolver can be imported standalone (@hookform/resolvers/zod) without pulling in the other 19 validation libraries. The only runtime dependency is @standard-schema/utils; every validation library (zod, yup, joi, ajv, valibot, etc.) is a peerDependency-like devDependency used only for building/testing that specific resolver, and react-hook-form itself is a peer dependency. Biome handles linting/formatting, vitest with jsdom runs tests, and lefthook manages git hooks. Code Quality Each resolver sub-package carries its own tests directory (21 test directories total across the monorepo) exercising success paths, validation-error shapes, sync/async modes, and the raw option; the shared toNestErrors/validateFieldsNatively utilities are exercised indirectly through every resolver’s test suite. The zod resolver in particular handles both Zod 3 and Zod 4 schema/error shapes via runtime type guards (isZod3Schema/isZod4Schema), showing deliberate attention to backward compatibility as the underlying ecosystem library evolves. Naming is consistent (each resolver exported as <lib>Resolver), and TypeScript overloads are used extensively to keep input/output type inference correct across each schema library’s own generic conventions. API Design The API surface is minimal by design: import one resolver function matching your schema library, pass it to useForm({ resolver }), done — no additional configuration objects beyond the schema itself and an optional {mode, raw} pair. This uniformity is the library’s core value: switching validation libraries (or supporting several in one design system) requires changing only the resolver import and the schema definition, not any form-handling code. The trade-off is that some resolvers carry sizable TypeScript overload sets (e.g. zodResolver has 4+ overloads to support Zod 3, Zod 4, and the raw option) which the type-inference benefit largely justifies, but adds surface complexity for anyone diving into the source rather than just consuming the published types.