From c1cfe5cafb3a75e7b05e8aeb9b85cfcffc3eca66 Mon Sep 17 00:00:00 2001
From: bill <bluebill1049@hotmail.com>
Date: Sat, 16 May 2026 11:47:01 +1000
Subject: [PATCH] feat: resetDefaultValues

---
 src/components/Menu/MenuLinks.ts              |   1 +
 .../docs/useform/resetdefaultvalues.mdx       | 142 ++++++++++++++++++
 2 files changed, 143 insertions(+)
 create mode 100644 src/content/docs/useform/resetdefaultvalues.mdx

diff --git a/src/components/Menu/MenuLinks.ts b/src/components/Menu/MenuLinks.ts
index 3821b262d..d5e5a6a32 100644
--- a/src/components/Menu/MenuLinks.ts
+++ b/src/components/Menu/MenuLinks.ts
@@ -111,6 +111,7 @@ export const apiLinks: Pages = [
       { pathname: "/docs/useform/handlesubmit", name: "handleSubmit" },
       { pathname: "/docs/useform/reset", name: "reset" },
       { pathname: "/docs/useform/resetfield", name: "resetField" },
+      { pathname: "/docs/useform/resetdefaultvalues", name: "resetDefaultValues" },
       { pathname: "/docs/useform/seterror", name: "setError" },
       { pathname: "/docs/useform/clearerrors", name: "clearErrors" },
       { pathname: "/docs/useform/setvalue", name: "setValue" },
diff --git a/src/content/docs/useform/resetdefaultvalues.mdx b/src/content/docs/useform/resetdefaultvalues.mdx
new file mode 100644
index 000000000..e2b5a2872
--- /dev/null
+++ b/src/content/docs/useform/resetdefaultvalues.mdx
@@ -0,0 +1,142 @@
+---
+title: resetDefaultValues
+description: Update the form's baseline default values without resetting current field values.
+metaDescription: Update the baseline default values after async operations like form submission, preserving in-flight user edits and recomputing dirty state in React Hook Form.
+sidebar: apiLinks
+---
+
+## \</> `resetDefaultValues:` <TypeText>`<T>(values: T, options?: Record<string, boolean>) => void`</TypeText>
+
+Update `_defaultValues` and recompute `dirtyFields`/`isDirty` against the new baseline without modifying the current form values. This is useful when a form disables submission while `!isDirty` — after a successful async submission you can advance the baseline to the submitted values so that only post-submit edits are considered dirty.
+
+### Props
+
+---
+
+| Name      |               | Type                                                        | Description                                                                                |
+| --------- | ------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `values`  |               | <TypeText>object</TypeText>                                 | The new default values to establish as the baseline. Recommended to provide the full object. |
+| `options` | `keepDirty`   | <TypeText>boolean</TypeText>                                | When set to `true`, existing `dirtyFields` state is preserved as-is rather than recomputed against the new baseline. |
+|           | `keepIsValid` | <TypeText>boolean</TypeText>                                | When set to `true`, validation is not re-run after the baseline update and `isValid` remains unchanged. |
+
+<Admonition type="important" title="Rules">
+
+- Current form values (what the user has typed) are **never** modified by this method — only the internal baseline used to compute dirty state changes.
+- `dirtyFields` and `isDirty` are recomputed against the new baseline unless `keepDirty` is set.
+
+</Admonition>
+
+**Examples:**
+
+---
+
+**After Async Submission**
+
+<TabGroup buttonLabels={["TS", "JS"]}>
+
+```tsx copy
+import { useForm } from "react-hook-form"
+
+interface FormValues {
+  firstName: string
+  lastName: string
+}
+
+export default function App() {
+  const {
+    register,
+    handleSubmit,
+    resetDefaultValues,
+    formState: { isDirty },
+  } = useForm<FormValues>({
+    defaultValues: { firstName: "", lastName: "" },
+  })
+
+  const onSubmit = async (data: FormValues) => {
+    await saveToServer(data)
+    // Advance the baseline to the submitted values.
+    // isDirty will now only be true if the user edits after this point.
+    resetDefaultValues(data)
+  }
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register("firstName")} />
+      <input {...register("lastName")} />
+      <button type="submit" disabled={!isDirty}>
+        Save
+      </button>
+    </form>
+  )
+}
+```
+
+```javascript copy
+import { useForm } from "react-hook-form"
+
+export default function App() {
+  const {
+    register,
+    handleSubmit,
+    resetDefaultValues,
+    formState: { isDirty },
+  } = useForm({
+    defaultValues: { firstName: "", lastName: "" },
+  })
+
+  const onSubmit = async (data) => {
+    await saveToServer(data)
+    // Advance the baseline to the submitted values.
+    // isDirty will now only be true if the user edits after this point.
+    resetDefaultValues(data)
+  }
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register("firstName")} />
+      <input {...register("lastName")} />
+      <button type="submit" disabled={!isDirty}>
+        Save
+      </button>
+    </form>
+  )
+}
+```
+
+</TabGroup>
+
+**With Options**
+
+```javascript copy
+import { useForm } from "react-hook-form"
+
+export default function App() {
+  const { register, resetDefaultValues } = useForm({
+    defaultValues: { firstName: "", lastName: "" },
+  })
+
+  const handleServerUpdate = (serverValues) => {
+    resetDefaultValues(serverValues, {
+      keepDirty: true,   // preserve existing dirty tracking
+      keepIsValid: true, // skip re-validation
+    })
+  }
+
+  return (
+    <form>
+      <input {...register("firstName")} />
+      <input {...register("lastName")} />
+      <button type="button" onClick={() => handleServerUpdate({ firstName: "Jane", lastName: "Doe" })}>
+        Load server values
+      </button>
+    </form>
+  )
+}
+```
+
+### Related
+
+---
+
+- [reset](/docs/useform/reset)
+- [resetField](/docs/useform/resetfield)