From 16bcd00d8aeb7d765c53c306cfc12f4eb854159d Mon Sep 17 00:00:00 2001
From: cahnory <cahnory@gmail.com>
Date: Thu, 16 Jul 2026 21:06:37 +0200
Subject: [PATCH] feat(react): support hook-level defaultValues overrides

---
 .changeset/rare-eels-juggle.md    |  6 ++++++
 libs/react/README.md              |  8 +++++++-
 libs/react/src/form-hook.ts       | 11 +++++++----
 libs/react/src/isomorphic-form.ts |  1 -
 4 files changed, 20 insertions(+), 6 deletions(-)
 create mode 100644 .changeset/rare-eels-juggle.md

diff --git a/.changeset/rare-eels-juggle.md b/.changeset/rare-eels-juggle.md
new file mode 100644
index 0000000..a5c53e9
--- /dev/null
+++ b/.changeset/rare-eels-juggle.md
@@ -0,0 +1,6 @@
+---
+"@tanstack-isomorphic-form/core": patch
+"@tanstack-isomorphic-form/react": patch
+---
+
+Allow `useIsomorphicForm(loaderData, options)` in the React package to accept hook-level `defaultValues`, using those values to seed idle form state for a specific hook instance while preserving the existing sanitizer behavior.
diff --git a/libs/react/README.md b/libs/react/README.md
index 89885bb..713163f 100644
--- a/libs/react/README.md
+++ b/libs/react/README.md
@@ -158,13 +158,19 @@ Represents an unexpected exception thrown while running the form action or loade
 - `formDataOptions`: optional parsing delimiters for nested keys
 - `returnedValueSanitizer`: optional function to normalize values stored in `formState`
 
-### `useIsomorphicForm(loaderData)`
+### `useIsomorphicForm(loaderData, options?)`
 
 Turns loader data into:
 
 - `formProps`: props to spread onto the `<form>`
 - `formState`: reactive state representing the current form lifecycle
 
+Hook options:
+
+- `defaultValues`: optional initial values for this hook instance; these seed `formState.values` and take precedence over defaults passed to the loader, which themselves take precedence over defaults configured on `createIsomorphicForm`
+- `onSuccess`: optional callback invoked after a successful action
+- `onError`: optional callback invoked for form-level errors and unexpected failures
+
 ### `formState`
 
 `formState.status` can be:
diff --git a/libs/react/src/form-hook.ts b/libs/react/src/form-hook.ts
index c9a6d07..8d935cc 100644
--- a/libs/react/src/form-hook.ts
+++ b/libs/react/src/form-hook.ts
@@ -46,13 +46,11 @@ type IsomorphicFormHookOptions<
 
 export const createIsomorphicFormHook =
   <const TSchema extends FormDataSchema, const TActionFn extends FormAction<TSchema>>({
-    defaultValues,
     formDataExtractor,
     actionFn,
     returnedValueSanitizer,
     schema,
   }: {
-    defaultValues?: InferFormDataSchemaExtract<TSchema> | undefined;
     formDataExtractor: FormDataExtractor<TSchema>;
     schema: TSchema;
     returnedValueSanitizer?: ValueSanitizer<TSchema> | undefined;
@@ -60,7 +58,7 @@ export const createIsomorphicFormHook =
   }): IsomorphicFormHook<TSchema, TActionFn> =>
   <const TActionUrl extends string>(
     { actionUrl, state }: Awaited<FormLoaderReturn<TSchema, TActionFn, TActionUrl>>,
-    { onError, onSuccess }: IsomorphicFormHookOptions<TSchema, TActionFn> = {},
+    { defaultValues, onError, onSuccess }: IsomorphicFormHookOptions<TSchema, TActionFn> = {},
   ) =>
     useIsomorphicForm({
       actionFn,
@@ -103,7 +101,12 @@ const useIsomorphicForm = <
 }): IsomorphicFormHookReturn<TSchema, TActionFn, TActionUrl> => {
   const navigate = useNavigate();
   const [formState, setFormState] = useState(
-    state.status === "idle" && defaultValues ? { ...state, values: defaultValues } : state,
+    state.status === "idle" && defaultValues
+      ? {
+          ...state,
+          values: returnedValueSanitizer ? returnedValueSanitizer(defaultValues) : defaultValues,
+        }
+      : state,
   );
   const submitRef = useRef(false);
 
diff --git a/libs/react/src/isomorphic-form.ts b/libs/react/src/isomorphic-form.ts
index 1fa5d7b..eac0e7c 100644
--- a/libs/react/src/isomorphic-form.ts
+++ b/libs/react/src/isomorphic-form.ts
@@ -41,7 +41,6 @@ export const createIsomorphicForm = <
     }),
     useIsomorphicForm: createIsomorphicFormHook({
       actionFn,
-      defaultValues,
       formDataExtractor,
       returnedValueSanitizer,
       schema,