mui · siriwatknp · Jun 6, 2025 · Jun 6, 2025
diff --git a/docs/data/material/integrations/nextjs/nextjs.md b/docs/data/material/integrations/nextjs/nextjs.md
@@ -118,7 +118,7 @@ Finally, in `src/app/layout.tsx`, pass the theme to the `ThemeProvider`:
 
 To learn more about theming, check out the [theming guide](/material-ui/customization/theming/) page.
 
-#### CSS theme variables
+### CSS theme variables
 
 To use [CSS theme variables](/material-ui/customization/css-theme-variables/overview/), enable the `cssVariables` flag:
 
@@ -243,6 +243,40 @@ To use a custom [Emotion cache](https://emotion.sh/docs/@emotion/cache), pass it
  };
 ```
 
+#### Cascade layers (optional)
+
+To enable [cascade layers](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_layers) (`@layer`), create a new cache with `enableCssLayer: true` and pass it to the `emotionCache` property in both `_document.tsx` and `_app.tsx`:
+
+```diff title="pages/_document.tsx"
++import { createEmotionCache } from '@mui/material-nextjs/v15-pagesRouter';
+ ...
+
+ MyDocument.getInitialProps = async (ctx) => {
+   const finalProps = await documentGetInitialProps(ctx, {
++    emotionCache: createEmotionCache({ enableCssLayer: true }),
+   });
+   return finalProps;
+ };
+```
+
+```diff title="pages/_app.tsx"
++import { createEmotionCache } from '@mui/material-nextjs/v15-pagesRouter';
+  ...
+
+const clientCache = createEmotionCache({ enableCssLayer: true });
+
++ export default function MyApp({ emotionCache = clientCache }) {
+    return (
++     <AppCacheProvider emotionCache={emotionCache}>
+        <Head>
+          ...
+        </Head>
+        ...
+      </AppCacheProvider>
+    );
+  }
+```
+
 #### App enhancement (optional)
 
 Pass an array to the `plugins` property to enhance the app with additional features, like server-side-rendered styles if you're using JSS and styled-components.

diff --git a/packages/mui-material-nextjs/src/v13-pagesRouter/createCache.ts b/packages/mui-material-nextjs/src/v13-pagesRouter/createCache.ts
@@ -5,7 +5,9 @@ const isBrowser = typeof document !== 'undefined';
 // On the client side, Create a meta tag at the top of the <head> and set it as insertionPoint.
 // This assures that MUI styles are loaded first.
 // It allows developers to easily override MUI styles with other styling solutions, like CSS modules.
-export default function createEmotionCache() {
+export default function createEmotionCache(
+  options?: { enableCssLayer?: boolean } & Parameters<typeof createCache>[0],
+) {
   let insertionPoint;
 
   if (isBrowser) {
@@ -15,5 +17,18 @@ export default function createEmotionCache() {
     insertionPoint = emotionInsertionPoint ?? undefined;
   }
 
-  return createCache({ key: 'mui', insertionPoint });
+  const { enableCssLayer, ...rest } = options ?? {};
+
+  const emotionCache = createCache({ key: 'mui', insertionPoint, ...rest });
+  if (enableCssLayer) {
+    const prevInsert = emotionCache.insert;
+    emotionCache.insert = (...args) => {
+      if (!args[1].styles.startsWith('@layer')) {
+        // avoid nested @layer
+        args[1].styles = `@layer mui {${args[1].styles}}`;
+      }
+      return prevInsert(...args);
+    };
+  }
+  return emotionCache;
 }
diff --git a/packages/mui-material-nextjs/src/v13-pagesRouter/index.ts b/packages/mui-material-nextjs/src/v13-pagesRouter/index.ts
@@ -1,2 +1,3 @@
 export * from './pagesRouterV13Document';
 export * from './pagesRouterV13App';
+export { default as createEmotionCache } from './createCache';
diff --git a/packages/mui-material-nextjs/src/v13-pagesRouter/pagesRouterV13Document.tsx b/packages/mui-material-nextjs/src/v13-pagesRouter/pagesRouterV13Document.tsx
@@ -99,14 +99,23 @@ export async function documentGetInitialProps(
         const { styles } = extractCriticalToChunks(initialProps.html);
         return {
           ...initialProps,
-          emotionStyleTags: styles.map((style) => (
-            <style
-              data-emotion={`${style.key} ${style.ids.join(' ')}`}
-              key={style.key}
-              // eslint-disable-next-line react/no-danger
-              dangerouslySetInnerHTML={{ __html: style.css }}
-            />
-          )),
+          emotionStyleTags: styles.map((style) => {
+            if (!style.css.trim()) {
+              return null;
+            }
+            const isLayerOrderRule = style.css.startsWith('@layer') && !style.css.match(/\{.*\}/);
+            return (
+              <style
+                // If the style is a layer order rule, prefix with the cache key to let Emotion hydrate this node.
+                // Otherwise, Emotion will hydrate only the non-global styles and they will override the layer order rule.
+                data-emotion={`${isLayerOrderRule ? `${cache.key} ` : ''}${style.key} ${style.ids.join(' ')}`}
+                key={style.key}
+                // eslint-disable-next-line react/no-danger
+                dangerouslySetInnerHTML={{ __html: style.css }}
+                nonce={cache.nonce}
+              />
+            );
+          }),
         };
       },
     },