diff --git a/src/components/Menu/MenuLinks.ts b/src/components/Menu/MenuLinks.ts
index d02ac99d6..40b6fccfd 100644
--- a/src/components/Menu/MenuLinks.ts
+++ b/src/components/Menu/MenuLinks.ts
@@ -129,6 +129,7 @@ export const apiLinks: Pages = [
{ pathname: "/docs/useform/setvalues", name: "setValues" },
{ pathname: "/docs/useform/setfocus", name: "setFocus" },
{ pathname: "/docs/useform/getvalues", name: "getValues" },
+ { pathname: "/docs/useform/geterrors", name: "getErrors" },
{ pathname: "/docs/useform/getfieldstate", name: "getFieldState" },
{ pathname: "/docs/useform/trigger", name: "trigger" },
{ pathname: "/docs/useform/control", name: "control" },
@@ -292,6 +293,10 @@ export const tsLinks: Pages = [
name: "UseFormGetValues",
pathname: "#UseFormGetValues",
},
+ {
+ name: "UseFormGetErrors",
+ pathname: "#UseFormGetErrors",
+ },
{
name: "UseFormGetFieldState",
pathname: "#UseFormGetFieldState",
diff --git a/src/content/docs/useform.mdx b/src/content/docs/useform.mdx
index b72e3b33e..c7f634153 100644
--- a/src/content/docs/useform.mdx
+++ b/src/content/docs/useform.mdx
@@ -67,6 +67,10 @@ sidebar: apiLinks
label: "getValues",
value: "/docs/useform/getvalues",
},
+ {
+ label: "getErrors",
+ value: "/docs/useform/geterrors",
+ },
{
label: "getFieldState",
value: "/docs/useform/getfieldstate",
@@ -845,6 +849,7 @@ The following list contains references to `useForm` return props.
- [setValues](/docs/useform/setvalues)
- [setFocus](/docs/useform/setfocus)
- [getValues](/docs/useform/getvalues)
+- [getErrors](/docs/useform/geterrors)
- [getFieldState](/docs/useform/getfieldstate)
- [trigger](/docs/useform/trigger)
- [control](/docs/useform/control)
diff --git a/src/content/docs/useform/geterrors.mdx b/src/content/docs/useform/geterrors.mdx
new file mode 100644
index 000000000..1f38e0164
--- /dev/null
+++ b/src/content/docs/useform/geterrors.mdx
@@ -0,0 +1,72 @@
+---
+title: getErrors
+description: Read current form errors without subscribing to re-renders.
+metaDescription: Read all, individual, or multiple currently stored form errors without running validation.
+sidebar: apiLinks
+---
+
+## \> `getErrors:` [UseFormGetErrors](/ts#UseFormGetErrors)
+
+**Note**: This API is planned for an upcoming React Hook Form release and has not yet shipped.
+
+`getErrors` reads the errors currently stored in the form without running validation, subscribing to error changes, or triggering re-renders. Use [`formState.errors`](/docs/useform/formstate) or [`useFormState`](/docs/useformstate) for reactive error UI.
+
+### Props
+
+---
+
+| Name | Type | Description |
+| ------ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name` | undefined | Returns all currently stored errors. |
+| | string | Returns the error at a field, parent, or global error path (`root`, `root.*`, `form`, or `form.*`), or `undefined`. Parent paths may return a nested error subtree. |
+| | string[] | Returns one result for each path in the same order. Missing errors remain `undefined`. |
+
+
+
+- Treat returned errors as read-only. Use [`setError`](/docs/useform/seterror) and [`clearErrors`](/docs/useform/clearerrors) to update the form's stored errors.
+
+
+
+##### Example
+
+---
+
+```tsx copy
+import { useForm } from "react-hook-form"
+
+type FormInputs = {
+ email: string
+ user: {
+ firstName: string
+ }
+}
+
+export default function App() {
+ const { register, getErrors } = useForm({
+ mode: "onChange",
+ })
+
+ const readErrors = () => {
+ const allErrors = getErrors()
+ const userErrors = getErrors("user")
+ const [emailError, firstNameError] = getErrors(["email", "user.firstName"])
+
+ console.log({
+ allErrors,
+ userErrors,
+ emailError,
+ firstNameError,
+ })
+ }
+
+ return (
+
+ )
+}
+```
diff --git a/src/content/ts.mdx b/src/content/ts.mdx
index 3891cf6cb..0f6cd9fa9 100644
--- a/src/content/ts.mdx
+++ b/src/content/ts.mdx
@@ -188,6 +188,7 @@ export type UseFormReturn<
> = {
watch: UseFormWatch
getValues: UseFormGetValues
+ getErrors: UseFormGetErrors
getFieldState: UseFormGetFieldState
setError: UseFormSetError
clearErrors: UseFormClearErrors
@@ -542,12 +543,7 @@ The type of the `setError` function.
```tsx copy
export type UseFormSetError = (
- name:
- | FieldPath
- | `root.${string}`
- | "root"
- | "form"
- | `form.${string}`,
+ name: FieldPath | ErrorNamespacePath,
error: ErrorOption,
options?: {
shouldFocus: boolean
@@ -567,10 +563,7 @@ export type UseFormClearErrors = (
| FieldPath
| FieldPath[]
| readonly FieldPath[]
- | `root.${string}`
- | "root"
- | "form"
- | `form.${string}`
+ | ErrorNamespacePath
) => void
```
@@ -649,6 +642,43 @@ export type UseFormGetValues = {
---
+## \> UseFormGetErrors {#UseFormGetErrors}
+
+The type of the `getErrors` function. This type is overloaded; it can be called with no arguments, a single error path, or an array of error paths.
+
+```tsx copy
+export type ErrorNamespacePath =
+ | "root"
+ | `root.${string}`
+ | "form"
+ | `form.${string}`
+
+export type GetErrorsResult<
+ TFieldValues extends FieldValues,
+ TName extends FieldPath | ErrorNamespacePath,
+> = TName extends "root"
+ ? (Record & GlobalError) | undefined
+ : TName extends ErrorNamespacePath
+ ? GlobalError | undefined
+ : TName extends FieldPath
+ ? FieldPathError | undefined
+ : never
+
+export type UseFormGetErrors = {
+ (name?: undefined): FieldErrors
+ | ErrorNamespacePath>(
+ name: TName
+ ): GetErrorsResult
+ | ErrorNamespacePath)[]>(
+ names: readonly [...TNames]
+ ): {
+ [K in keyof TNames]: GetErrorsResult
+ }
+}
+```
+
+---
+
## \> UseFormGetFieldState {#UseFormGetFieldState}
The type of the `getFieldState` function.