diff --git a/jsr.json b/jsr.json
index f9696985231dbfda1713548dcc4cd9617186b54a..f61edd0bbff8b9ed46023554385d2776b4f5dd83 100644
--- a/jsr.json
+++ b/jsr.json
@@ -1,6 +1,6 @@
 {
   "name": "@clo/react-mutation",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "exports": {
     ".": "./src/mod.ts",
     "./tanstack-query.ts": "./src/tanstack-query.ts",
diff --git a/readme.changes.md b/readme.changes.md
index 0040a81d93071d486d759f82c41565daa7484d12..238c2556e6070a5d62519d821cd64bdc9f082947 100644
--- a/readme.changes.md
+++ b/readme.changes.md
@@ -1,5 +1,11 @@
 # notable changes in React Mutation
 
+## v2
+
+### breaking
+
+- rename `onSuccess` and `onSuccessDataOnly` to `onSuccessUi` and `onSuccessData`.
+
 ## v1.1
 
 - Add `runAsHeadlessPromise`. The function name is intentionally long to avoid using it, please use `runWithOptions` instead.
diff --git a/src/mutation.ts b/src/mutation.ts
index ff43c18ed7c4a4b758b37fbdf6a1d6c2cbf9b98d..5093a65167227bd5a13a08f8af5ef9b14e17aee3 100644
--- a/src/mutation.ts
+++ b/src/mutation.ts
@@ -273,13 +273,13 @@ export class BlockingMutation<
     }
 
     const args = array.slice() as Args;
-    const { onSuccess, onSuccessDataOnly, onError, onSettled, onRestore } = args
+    const { onSuccessUi: onSuccess, onSuccessData, onError, onSettled, onRestore } = args
       .pop() as RunOptions<Result>;
     const promise = this.#runWithOptions(args, onRestore, true);
     return promise.then((result) => {
       // Call user handlers
       onSuccess?.(result);
-      onSuccessDataOnly?.(result);
+      onSuccessData?.(result);
       onSettled?.({ status: "success", result });
       return result;
     }).catch((caught: unknown) => {
@@ -305,17 +305,17 @@ export class BlockingMutation<
     }
 
     const args = array.slice() as Args;
-    const { onSuccess, onSuccessDataOnly, onError, onSettled, onRestore } = args
+    const { onSuccessUi, onSuccessData, onError, onSettled, onRestore } = args
       .pop() as RunOptions<Result>;
-    const suppressAll = this.#options.debounceMs !== undefined && !onSuccess && !onError;
-    const suppressGlobalSuccess = onSuccess !== undefined || suppressAll;
+    const suppressAll = this.#options.debounceMs !== undefined && !onSuccessUi && !onError;
+    const suppressGlobalSuccess = onSuccessUi !== undefined || suppressAll;
     const suppressGlobalError = onError !== undefined || suppressAll;
 
     const promise = this.#runWithOptions(args, onRestore, suppressAll);
     promise.then((result) => {
       // Call user handlers
-      onSuccess?.(result);
-      onSuccessDataOnly?.(result);
+      onSuccessUi?.(result);
+      onSuccessData?.(result);
       onSettled?.({ status: "success", result });
 
       // Call global handler unless suppressed
diff --git a/src/react.ts b/src/react.ts
index 6462c991275cca0158510e7c2e9bb6f3c4e3630d..3307dd5d5a9aaf5c997a25cab38cfdc1bf2892af 100644
--- a/src/react.ts
+++ b/src/react.ts
@@ -261,7 +261,7 @@ class Observer<Args extends unknown[], Result> {
     const promise = mutation.runWithOptions(
       ...args,
       {
-        onSuccess: watchesSuccess ? () => {} : undefined,
+        onSuccessUi: watchesSuccess ? () => {} : undefined,
         onError: watchesError ? () => {} : undefined,
         // For debounced mutations, suppress global handlers in runWithOptions
         // The debounce logic (#enqueueDebouncedCall) will call them once if needed
diff --git a/src/types.ts b/src/types.ts
index d4dc0f2d8e1c916c44f60f5b55727fd43745aa31..6e9ec6b8dfdb11aa1213fac8982316a1f6f79eb2 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -29,10 +29,14 @@ export interface Mutation<Args extends unknown[], Result> {
 }
 
 export interface RunOptions<Result> {
-  /** Called on success, suppresses the global success handler */
-  onSuccess?: (result: Result) => void;
-  /** Called on success, does NOT suppress the global success handler */
-  onSuccessDataOnly?: (result: Result) => void;
+  /** Called to show the success UI. Passing this suppresses the global success handler. */
+  onSuccessUi?: (result: Result) => void;
+  /**
+   * Called with result data, but unlike `onSuccessUi`, this indicates the
+   * caller is not concerned with the UI flow of the success. Passing this
+   * does NOT suppress the global success handler.
+   */
+  onSuccessData?: (result: Result) => void;
   /** Called on error, suppresses the global error handler */
   onError?: (error: unknown) => void;
   /** Called on settled (doesn't suppress global handlers) */
diff --git a/test/ordering.test.ts b/test/ordering.test.ts
index 9ae1f4351c1f0292d64a3a96b202bebf64af1661..b7284a41c2a7a23ac03d175367a2689dd563e7cc 100644
--- a/test/ordering.test.ts
+++ b/test/ordering.test.ts
@@ -378,7 +378,7 @@ test("runWithOptions callbacks: onSuccess called before global handler", async (
   });
 
   mutTest.runWithOptions({
-    onSuccess: () => {
+    onSuccessUi: () => {
       calls.push("onSuccess");
     },
     onSettled: () => {
diff --git a/test/runWithOptions.test.tsx b/test/runWithOptions.test.tsx
index bf166a73a71943fdfc379cec047c7c1cf55f2a78..77f290ac0abe69e884519255415888c1a22570fc 100644
--- a/test/runWithOptions.test.tsx
+++ b/test/runWithOptions.test.tsx
@@ -32,7 +32,7 @@ test("runWithOptions should allow react hook to do local handling", async () =>
       <button
         data-testid="a"
         onClick={() => {
-          runWithOptions({ onSuccessDataOnly: () => {} });
+          runWithOptions({ onSuccessData: () => {} });
         }}
       >
         button