fix: prevent fetcher formData race condition in optimistic UI (#14506)

.changeset/fix-fetcher-formdata-race-condition.md

@@ -0,0 +1,9 @@
+---
+"react-router": patch
+---
+
+Fix fetcher race condition where formData was cleared before new loaderData was available, causing UI flicker in optimistic updates
+
+- Fixes issue where fetcher.formData became undefined before new loaderData was committed, causing a flicker in optimistic UI updates
+- Ensures atomic update of fetcher state and loaderData during navigation completion
+- Prevents UI flickering when using optimistic updates with fetchers

contributors.yml

@@ -352,6 +352,7 @@
 - sanjai451
 - sanketshah19
 - sapphi-red
+- SarthakRawat-1
 - saul-atomrigs
 - sbolel
 - scarf005

packages/react-router/__tests__/router/fetcher-race-condition-test.ts

@@ -0,0 +1,96 @@
+import type { Router } from "../../lib/router/router";
+import { createRouter } from "../../lib/router/router";
+import { createMemoryHistory } from "../../lib/router/history";
+import { sleep } from "./utils/utils";
+
+describe("Issue #14506: Fetcher race condition with optimistic UI", () => {
+  let router: Router;
+
+  afterEach(() => {
+    router?.dispose();
+  });
+
+  it("should keep formData available until loaderData updates (no flicker)", async () => {
+    let itemStatus = false;
+
+    router = createRouter({
+      history: createMemoryHistory({ initialEntries: ["/"] }),
+      routes: [
+        {
+          id: "root",
+          path: "/",
+          children: [
+            {
+              id: "item",
+              path: "item",
+              loader: async () => {
+                await sleep(5);
+                return { status: itemStatus };
+              },
+              action: async ({ request }) => {
+                let formData = await request.formData();
+                itemStatus = formData.get("status") === "true";
+                await sleep(5);
+                return { success: true };
+              },
+            },
+          ],
+        },
+      ],
+    });
+
+    router.initialize();
+    await router.navigate("/item");
+
+    // Track what UI sees using the pattern from the issue
+    let transitions: Array<{
+      fetcherState: string;
+      hasFormData: boolean;
+      loaderDataStatus: boolean;
+      uiDisplays: boolean;
+    }> = [];
+
+    router.subscribe((state) => {
+      let fetcher = state.fetchers.get("toggle");
+      let loaderData = state.loaderData["item"];
+
+      if (fetcher) {
+        // Exact pattern from issue: const status = (fetcher.formData?.get('status') === 'true') ?? item.status
+        let displayedStatus =
+          (fetcher.formData && fetcher.formData.get("status") === "true") ??
+          loaderData?.status ??
+          false;
+
+        transitions.push({
+          fetcherState: fetcher.state,
+          hasFormData: fetcher.formData !== undefined,
+          loaderDataStatus: loaderData?.status ?? false,
+          uiDisplays: displayedStatus,
+        });
+      }
+    });
+
+    let formData = new FormData();
+    formData.append("status", "true");
+
+    await router.fetch("toggle", "item", "/item", {
+      formMethod: "POST",
+      formData,
+    });
+
+    await sleep(50);
+
+    // Check for flicker: true -> false -> true
+    let uiValues = transitions.map(t => t.uiDisplays);
+    let hasFlicker = false;
+    for (let i = 0; i < uiValues.length - 2; i++) {
+      if (uiValues[i] === true && uiValues[i + 1] === false && uiValues[i + 2] === true) {
+        hasFlicker = true;
+        break;
+      }
+    }
+
+    expect(hasFlicker).toBe(false);
+    expect(uiValues[uiValues.length - 1]).toBe(true);
+  });
+});

packages/react-router/lib/router/router.ts

@@ -1363,6 +1363,19 @@ export function createRouter(init: RouterInit): Router {
         )
       : state.loaderData;
 
+    // Transition any fetchers that were kept in loading state (with formData) to idle
+    // now that we're committing the loaderData. This ensures the fetcher state change
+    // and loaderData update happen atomically in the same updateState() call.
+    let fetchers = newState.fetchers ? new Map(newState.fetchers) : new Map(state.fetchers);
+    let updatedFetchers = false;
+    fetchers.forEach((fetcher, key) => {
+      if (fetcher.state === "loading" && fetcher.formData) {
+        // Transition to idle now that loaderData is being committed
+        fetchers.set(key, getDoneFetcher(fetcher.data));
+        updatedFetchers = true;
+      }
+    });
+
     // On a successful navigation we can assume we got through all blockers
     // so we can start fresh
     let blockers = state.blockers;
@@ -1436,7 +1449,7 @@ export function createRouter(init: RouterInit): Router {
 
     updateState(
       {
-        ...newState, // matches, errors, fetchers go through as-is
+        ...newState, // matches, errors go through as-is
         actionData,
         loaderData,
         historyAction: pendingAction,
@@ -1447,6 +1460,8 @@ export function createRouter(init: RouterInit): Router {
         restoreScrollPosition,
         preventScrollReset,
         blockers,
+        // Use updated fetchers if we transitioned any from loading to idle
+        ...(updatedFetchers ? { fetchers } : {}),
       },
       {
         viewTransitionOpts,
@@ -6549,8 +6564,22 @@ function processLoaderData(
         // keep this to type narrow to a success result in the else
         invariant(false, "Unhandled fetcher revalidation redirect");
       } else {
+        // Get the current fetcher state to check if it has formData
+        let existingFetcher = state.fetchers.get(key);
         let doneFetcher = getDoneFetcher(result.data);
-        state.fetchers.set(key, doneFetcher);
+
+        // If the fetcher currently has formData, keep it
+        // in loading state with the new data until completeNavigation commits both
+        // the fetcher state and loaderData together. This prevents a flicker where
+        // fetcher.formData becomes undefined before new loaderData is available.
+        if (existingFetcher && existingFetcher.formData) {
+          state.fetchers.set(key, {
+            ...existingFetcher,
+            data: result.data,
+          });
+        } else {
+          state.fetchers.set(key, doneFetcher);
+        }
       }
     });