mui · siriwatknp · Apr 11, 2025 · Mar 17, 2025 · Mar 17, 2025 · Mar 17, 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.
@@ -361,7 +395,7 @@ To integrate [Next.js font optimization](https://nextjs.org/docs/pages/building-
 
 To learn more about theming, check out the [Theming guide](/material-ui/customization/theming/).
 
-#### CSS theme variables
+### CSS theme variables
 
 To use [CSS theme variables](/material-ui/customization/css-theme-variables/overview/), enable the `cssVariables` flag:
 

diff --git a/docs/package.json b/docs/package.json
@@ -53,6 +53,7 @@
     "@mui/x-tree-view": "7.28.1",
     "@popperjs/core": "^2.11.8",
     "@react-spring/web": "^9.7.5",
+    "@tailwindcss/postcss": "^4.1.3",
     "@toolpad/core": "^0.12.1",
     "autoprefixer": "^10.4.21",
     "autosuggest-highlight": "^3.3.4",
@@ -139,7 +140,7 @@
     "marked": "^15.0.7",
     "playwright": "^1.51.1",
     "prettier": "^3.5.3",
-    "tailwindcss": "^3.4.17",
+    "tailwindcss": "^4.1.3",
     "yargs": "^17.7.2"
   }
 }
diff --git a/docs/pages/global.css b/docs/pages/global.css
@@ -1,3 +1,3 @@
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
+@import 'tailwindcss/theme.css' layer(theme);
+@import 'tailwindcss/utilities.css' layer(utilities);
+@config '../tailwind.config.mjs';
diff --git a/docs/postcss.config.js b/docs/postcss.config.js
@@ -1,7 +1,6 @@
 module.exports = {
   plugins: {
     'postcss-import': {},
-    'tailwindcss/nesting': {},
-    tailwindcss: {},
+    '@tailwindcss/postcss': {},
   },
 };
diff --git a/docs/src/createEmotionCache.ts b/docs/src/createEmotionCache.ts
@@ -1,8 +1,13 @@
-import createCache from '@emotion/cache';
+import { createEmotionCache as createCache } from '@mui/material-nextjs/v15-pagesRouter';
 import { prefixer } from 'stylis';
 import globalSelector from './modules/utils/globalSelector';
 
 export default function createEmotionCache() {
   // TODO remove prepend: true once JSS is out
-  return createCache({ key: 'css', prepend: true, stylisPlugins: [prefixer, globalSelector] });
+  return createCache({
+    key: 'css',
+    prepend: true,
+    enableCssLayer: true,
+    stylisPlugins: [prefixer, globalSelector],
+  });
 }
diff --git a/docs/src/modules/components/AppSearch.js b/docs/src/modules/components/AppSearch.js
@@ -335,6 +335,7 @@ export default function AppSearch(props) {
   useLazyCSS(
     'https://cdn.jsdelivr.net/npm/@docsearch/css@3.0.0-alpha.40/dist/style.min.css',
     '#app-search',
+    { layer: 'docsearch' },
   );
   const FADE_DURATION = 120; // ms
   const t = useTranslate();

diff --git a/docs/src/modules/utils/StyledEngineProvider.js b/docs/src/modules/utils/StyledEngineProvider.js
@@ -2,16 +2,18 @@ import * as React from 'react';
 import PropTypes from 'prop-types';
 import { StyleSheetManager } from 'styled-components';
 import { CacheProvider } from '@emotion/react';
-import createCache from '@emotion/cache';
+import { createEmotionCache as createCache } from '@mui/material-nextjs/v15-pagesRouter';
 import { prefixer } from 'stylis';
 import rtlPlugin from 'stylis-plugin-rtl';
+import GlobalStyles from '@mui/material/GlobalStyles';
 import { ThemeOptionsContext } from 'docs/src/modules/components/ThemeContext';
 import globalSelector from './globalSelector';
 
 // Cache for the rtl version of the styles
 const cacheRtl = createCache({
   key: 'rtl',
   prepend: true,
+  enableCssLayer: true,
   stylisPlugins: [prefixer, rtlPlugin, globalSelector],
 });
 
@@ -24,7 +26,10 @@ export default function StyledEngineProvider(props) {
 
   return (
     <StyleSheetManager stylisPlugins={rtl ? [rtlPlugin] : []}>
-      <CacheProvider value={emotionCache}>{children}</CacheProvider>
+      <CacheProvider value={emotionCache}>
+        <GlobalStyles styles="@layer theme, docsearch, mui, utilities;" />
+        {children}
+      </CacheProvider>
     </StyleSheetManager>
   );
 }

diff --git a/docs/src/modules/utils/useLazyCSS.ts b/docs/src/modules/utils/useLazyCSS.ts
@@ -2,16 +2,70 @@ import * as React from 'react';
 import { loadCSS } from 'fg-loadcss';
 
 /**
- * Convenience wrapper around fgLoadCSS for hooks usage
- * @param {string} href
- * @param {string} before - CSS selector
+ * Enhanced lazy CSS loader that wraps CSS in a layer using fetch to avoid CORS issues
+ * @param {string} href - URL of the CSS file to load
+ * @param {string} before - CSS selector to insert before
+ * @param {object} options - Additional options
+ * @param {string} options.layer - Optional CSS layer name to wrap the CSS in
  * @returns {() => void} cleanup function
  */
-export default function useLazyCSS(href: string, before: string) {
+export default function useLazyCSS(href: string, before: string, options: { layer?: string } = {}) {
   React.useEffect(() => {
-    const link = loadCSS(href, document.querySelector(before) as HTMLElement);
+    // If no layer is specified, add style and clean it on unmount
+    if (!options.layer) {
+      const link = loadCSS(href, document.querySelector(before) as HTMLElement);
+      return () => {
+        link.parentElement?.removeChild(link);
+      };
+    }
+
+    // With layer option, we need to fetch the CSS content and wrap it
+    let styleElement: HTMLStyleElement | null = null;
+    const abortController = new AbortController();
+
+    // Fetch the CSS content directly to avoid CORS issues with cssRules
+    fetch(href, { signal: abortController.signal })
+      .then((response) => {
+        if (!response.ok) {
+          throw new Error(`Failed to fetch CSS: ${response.statusText}`);
+        }
+        return response.text();
+      })
+      .then((cssText) => {
+        // Create a style element with the CSS wrapped in the specified layer
+        styleElement = document.createElement('style');
+        styleElement.setAttribute('data-href', href);
+        styleElement.textContent = `@layer ${options.layer} {\n${cssText}\n}`;
+
+        // Insert at the specified position
+        const beforeElement = document.querySelector(before);
+        if (beforeElement?.parentNode) {
+          beforeElement.parentNode.insertBefore(styleElement, beforeElement);
+        } else {
+          document.head.appendChild(styleElement);
+        }
+      })
+      .catch((error) => {
+        // Ignore abort errors, log others
+        if (error.name !== 'AbortError') {
+          if (process.env.NODE_ENV !== 'production') {
+            console.error('Error loading CSS with layer:', error);
+          }
+
+          // Fall back to regular link element if fetch fails
+          styleElement = loadCSS(href, document.querySelector(before) as HTMLElement);
+        }
+      });
+
+    // Cleanup function
     return () => {
-      link.parentElement?.removeChild(link);
+      // Cancel any pending fetch
+      abortController.abort();
+
+      // Remove the style element if it was created
+      if (styleElement && styleElement.parentElement) {
+        styleElement.parentElement.removeChild(styleElement);
+      }
     };
-  }, [href, before]);
+  }, [href, before, options.layer]);
 }
diff --git a/docs/tailwind.config.js → docs/tailwind.config.mjs b/docs/tailwind.config.js → docs/tailwind.config.mjs
@@ -2,10 +2,10 @@
 // eslint-disable-next-line import/no-import-module-exports
 import plugin from 'tailwindcss/plugin';
 
-const defaultTheme = require('tailwindcss/defaultTheme');
+import defaultTheme from 'tailwindcss/defaultTheme';
 
 /** @type {import('tailwindcss').Config} */
-module.exports = {
+export default {
   darkMode: ['class', '[data-mui-color-scheme="dark"]'],
   content: [
     './data/**/*.{js,ts,jsx,tsx,mdx}',
@@ -55,10 +55,6 @@ module.exports = {
       },
     },
   },
-  corePlugins: {
-    // Remove the Tailwind CSS preflight styles so it can use Material UI's preflight instead (CssBaseline).
-    preflight: false,
-  },
   plugins: [
     plugin(({ addVariant }) => {
       [

diff --git a/packages/mui-material-nextjs/src/v13-pagesRouter/createCache.ts b/packages/mui-material-nextjs/src/v13-pagesRouter/createCache.ts
@@ -1,11 +1,13 @@
-import createCache, { Options } from '@emotion/cache';
+import createCache from '@emotion/cache';
 
 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(options?: Partial<Options>) {
+export default function createEmotionCache(
+  options?: { enableCssLayer?: boolean } & Parameters<typeof createCache>[0],
+) {
   let insertionPoint;
 
   if (isBrowser) {
@@ -15,5 +17,18 @@ export default function createEmotionCache(options?: Partial<Options>) {
     insertionPoint = emotionInsertionPoint ?? undefined;
   }
 
-  return createCache({ key: 'mui', insertionPoint, ...options });
+  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/pagesRouterV13Document.tsx b/packages/mui-material-nextjs/src/v13-pagesRouter/pagesRouterV13Document.tsx
@@ -102,17 +102,23 @@ export async function documentGetInitialProps(
         const { styles } = extractCriticalToChunks(initialProps.html);
         return {
           ...initialProps,
-          emotionStyleTags: styles.map((style) =>
-            style.css.trim() ? (
+          emotionStyleTags: styles.map((style) => {
+            if (!style.css.trim()) {
+              return null;
+            }
+            const isLayerOrderRule = style.css.startsWith('@layer') && !style.css.match(/\{.*\}/);
+            return (
               <style
-                data-emotion={`${style.key} ${style.ids.join(' ')}`}
+                // 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}
               />
-            ) : null,
-          ),
+            );
+          }),
         };
       },
     },