Remove leftover critical CSS on hydration mismatch (#13995)

markdalgleish · brophdawg11 · web-flow · commit b6c5168400ab · 2025-07-15T09:41:39.000-04:00
* Remove leftover critical CSS on hydration mismatch

* Update .changeset/lucky-hotels-complain.md

---------

Co-authored-by: Matt Brophy &lt;matt@brophy.org&gt;
diff --git a/.changeset/lucky-hotels-complain.md b/.changeset/lucky-hotels-complain.md
@@ -0,0 +1,5 @@
+---
+"react-router": patch
+---
+
+[REMOVE] (continuation of #13872) In Framework Mode, remove leftover critical CSS elements in development after initial render if there's a hydration mismatch
diff --git a/packages/react-router/lib/dom-export/hydrated-router.tsx b/packages/react-router/lib/dom-export/hydrated-router.tsx
@@ -24,6 +24,7 @@ import {
   UNSAFE_hydrationRouteProperties as hydrationRouteProperties,
   UNSAFE_createClientRoutesWithHMRRevalidationOptOut as createClientRoutesWithHMRRevalidationOptOut,
 } from "react-router";
+import { CRITICAL_CSS_DATA_ATTRIBUTE } from "../dom/ssr/components";
 import { RouterProvider } from "./dom-router-provider";
 
 type SSRInfo = {
@@ -242,6 +243,22 @@ export function HydratedRouter(props: HydratedRouterProps) {
       setCriticalCss(undefined);
     }
   }, []);
+  React.useEffect(() => {
+    if (process.env.NODE_ENV === "development" && criticalCss === undefined) {
+      // When there's a hydration mismatch, React 19 ignores the server HTML and
+      // re-renders from the root, but it doesn't remove any head tags that
+      // aren't present in the virtual DOM. This means that the original
+      // critical CSS elements are still in the document even though we cleared
+      // them in the effect above. To fix this, this effect is designed to clean
+      // up any leftover elements. If `criticalCss` is undefined in this effect,
+      // this means that React is no longer managing the critical CSS elements,
+      // so if there are any left in the document, these are stale elements from
+      // the original SSR pass and we can safely remove them.
+      document
+        .querySelectorAll(`[${CRITICAL_CSS_DATA_ATTRIBUTE}]`)
+        .forEach((element) => element.remove());
+    }
+  }, [criticalCss]);
 
   let [location, setLocation] = React.useState(router.state.location);
 
diff --git a/packages/react-router/lib/dom/ssr/components.tsx b/packages/react-router/lib/dom/ssr/components.tsx
@@ -212,6 +212,8 @@ function getActiveMatches(
   return matches;
 }
 
+export const CRITICAL_CSS_DATA_ATTRIBUTE = "data-react-router-critical-css";
+
 /**
   Renders all of the `<link>` tags created by route module {@link LinksFunction} export. You should render it inside the `<head>` of your document.
 
@@ -247,10 +249,17 @@ export function Links() {
   return (
     <>
       {typeof criticalCss === "string" ? (
-        <style dangerouslySetInnerHTML={{ __html: criticalCss }} />
+        <style
+          {...{ [CRITICAL_CSS_DATA_ATTRIBUTE]: "" }}
+          dangerouslySetInnerHTML={{ __html: criticalCss }}
+        />
       ) : null}
       {typeof criticalCss === "object" ? (
-        <link rel="stylesheet" href={criticalCss.href} />
+        <link
+          {...{ [CRITICAL_CSS_DATA_ATTRIBUTE]: "" }}
+          rel="stylesheet"
+          href={criticalCss.href}
+        />
       ) : null}
       {keyedLinks.map(({ key, link }) =>
         isPageLinkDescriptor(link) ? (

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"react-router": patch
 +---
++
 +[REMOVE] (continuation of #13872) In Framework Mode, remove leftover critical CSS elements in development after initial render if there's a hydration mismatch