docs: add getErrors API documentation

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",

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)

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:` <TypeText>[UseFormGetErrors](/ts#UseFormGetErrors)</TypeText>
+
+**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` | <TypeText>undefined</TypeText> | Returns all currently stored errors.                                                                                                                                |
+|        | <TypeText>string</TypeText>    | 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. |
+|        | <TypeText>string[]</TypeText>  | Returns one result for each path in the same order. Missing errors remain `undefined`.                                                                              |
+
+<Admonition type="important" title="Rules">
+
+- Treat returned errors as read-only. Use [`setError`](/docs/useform/seterror) and [`clearErrors`](/docs/useform/clearerrors) to update the form's stored errors.
+
+</Admonition>
+
+##### Example
+
+---
+
+```tsx copy
+import { useForm } from "react-hook-form"
+
+type FormInputs = {
+  email: string
+  user: {
+    firstName: string
+  }
+}
+
+export default function App() {
+  const { register, getErrors } = useForm<FormInputs>({
+    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 (
+    <form>
+      <input {...register("email", { required: true })} />
+      <input {...register("user.firstName", { required: true })} />
+      <button type="button" onClick={readErrors}>
+        Read errors
+      </button>
+    </form>
+  )
+}
+```

src/content/ts.mdx

@@ -188,6 +188,7 @@ export type UseFormReturn<
 > = {
   watch: UseFormWatch<TFieldValues>
   getValues: UseFormGetValues<TFieldValues>
+  getErrors: UseFormGetErrors<TFieldValues>
   getFieldState: UseFormGetFieldState<TFieldValues>
   setError: UseFormSetError<TFieldValues>
   clearErrors: UseFormClearErrors<TFieldValues>
@@ -542,12 +543,7 @@ The type of the `setError` function.
 
 ```tsx copy
 export type UseFormSetError<TFieldValues extends FieldValues> = (
-  name:
-    | FieldPath<TFieldValues>
-    | `root.${string}`
-    | "root"
-    | "form"
-    | `form.${string}`,
+  name: FieldPath<TFieldValues> | ErrorNamespacePath,
   error: ErrorOption,
   options?: {
     shouldFocus: boolean
@@ -567,10 +563,7 @@ export type UseFormClearErrors<TFieldValues extends FieldValues> = (
     | FieldPath<TFieldValues>
     | FieldPath<TFieldValues>[]
     | readonly FieldPath<TFieldValues>[]
-    | `root.${string}`
-    | "root"
-    | "form"
-    | `form.${string}`
+    | ErrorNamespacePath
 ) => void
 ```
 
@@ -649,6 +642,43 @@ export type UseFormGetValues<TFieldValues extends FieldValues> = {
 
 ---
 
+## \</> 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<TFieldValues> | ErrorNamespacePath,
+> = TName extends "root"
+  ? (Record<string, GlobalError> & GlobalError) | undefined
+  : TName extends ErrorNamespacePath
+    ? GlobalError | undefined
+    : TName extends FieldPath<TFieldValues>
+      ? FieldPathError<TFieldValues, TName> | undefined
+      : never
+
+export type UseFormGetErrors<TFieldValues extends FieldValues> = {
+  (name?: undefined): FieldErrors<TFieldValues>
+  <TName extends FieldPath<TFieldValues> | ErrorNamespacePath>(
+    name: TName
+  ): GetErrorsResult<TFieldValues, TName>
+  <TNames extends (FieldPath<TFieldValues> | ErrorNamespacePath)[]>(
+    names: readonly [...TNames]
+  ): {
+    [K in keyof TNames]: GetErrorsResult<TFieldValues, TNames[K]>
+  }
+}
+```
+
+---
+
 ## \</> UseFormGetFieldState {#UseFormGetFieldState}
 
 The type of the `getFieldState` function.