feat: resetDefaultValues

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

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)