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.