Clarify structure of nested errors in a custom resolver (#1160)

DLiblik · web-flow · commit 35291ad06482 · 2025-07-15T13:16:38.000+10:00
* Clarify structure of nested errors in a custom resolver

The existing documentation infers that the return value of the `errors` key on a custom resolver should use flat keys that match the path of the error (since this is the convention throughout the lib), however it turns out that the internal code for RHF actually expects a hierarchy to be returned... kept me up till 3am last night tracking this one down 😅  - RHF is awesome!

* Fix incomplete path in example snippet
diff --git a/src/content/docs/useform.mdx b/src/content/docs/useform.mdx
@@ -435,7 +435,10 @@ npm install @hookform/resolvers
 - A resolver can not be used with the built-in validators (e.g.: required, min, etc.)
 - When building a custom resolver:
   - Make sure that you return an object with both `values` and `errors` properties. Their default values should be an empty object. For example: `{}`.
-  - The keys of the `error` object should match the `name` values of your fields.
+  - The keys of the `errors` object should match the `name` values of your fields, but they _must_ be hierarchical rather than a single key for deep errors:
+    `❌ { "participants.1.name": someErr }` will not set or clear properly - instead, use `✅ { participants: [null, { name: someErr } ] }` as this is reachable
+    as `errors.participants[1].name` - you can still prepare your errors using flat keys, and then use a function like this one from the zod resolver:
+    [toNestErrors(flatErrs, resolverOptions)](https://github.com/react-hook-form/resolvers/blob/master/src/toNestErrors.ts)
 
 </Admonition>
 
