[material-nextjs] Add option to enable CSS layers for pages router

[siriwatknp]

Docs: https://deploy-preview-45596--material-ui.netlify.app/material-ui/integrations/nextjs/#pages-router

closes #45220

part of #44700

Motivation

To unblock Tailwind CSS v4 integration. Only pages router is missing this option.

Next.js App router and Vite (via StyledEngineProvider) are already supported.

Changes for @mui/material-nextjs

export createEmotionCache

Add option enableCssLayer to pages router createEmotionCache and reexport it.
The logic of CSS layer wrapping is the same as App Router and StyledEngineProvider.

update SSR emotion styles

Required to make it work with Tailwind CSS v4 or other CSS layer implementation.
The setup requires a GlobalStyles component to configure the order of layers.

<GlobalStyles styles="@layer theme, base, mui, components, utilities" />
// mui = Material UI component layer, the rest are default Tailwind CSS layers.
// This config makes the utilities classes override Material UI components without `!important`.

// The <GlobalStyles> needs to come before any Material UI components, so that it's injected first

This is the before:

Screen.Recording.2568-03-17.at.15.31.54.mov

In summary, the flicker occurs at hydration phase because Emotion hydrates at cache creation step.

Emotion hydrates only <style data-emotion="mui *"> (see the file) which does not include global styles, causing the CSS layer order declaration to appear below component styles.

Here is what happens chronologically:

1. on the server ✅

// on the server, the order is correct
<style data-emotion="mui-global …">@layer theme, base, mui, components, utilities;<style>
<style data-emotion="mui …">@mui { .MuiButton-…}</style>

2. at hydration phase ❌

// at hydration phase, the component styles appear first because of Emotion hydration logic
<style data-emotion="mui …">@mui { .MuiButton-…}</style>
…
<style data-emotion="mui-global …">@layer theme, base, mui, components, utilities;<style>
<style>
 // Tailwind CSS
 @layer theme, base, components, utilities;
 </style>

So, at hydration phase, Tailwind base styles will override Material UI components causing the flicker.

3. After the hydration phase, the flicker disappear because the GlobalStyles renders and the layer order is moved the top of the component styles. ✅

// after hydration, first render
<style data-emotion="mui-global …">@layer theme, base, mui, components, utilities;<style>
<style data-emotion="mui …">@mui { .MuiButton-…}</style>

---

After updating the file, there is no flicker because the layer order is always at the top before any component/global styles.

Screen.Recording.2568-03-17.at.15.25.25.mov

Upgrade Tailwind CSS to v4

Upgrading Tailwind CSS to v4 to dogfood the API added to @mui/material-nextjs and to experience the impact on adopting CSS layer.

By moving to CSS layer, I have to update the useLazyCSS to wrap the docsearch cdn CSS with @layer docsearch too, otherwise it won't be overridden by Material UI styled.

---

• I have followed (at least) the PR section of the contributing guide.

[mui-bot]

Netlify deploy preview

• docs/data/material/integrations/nextjs/nextjs.md

Bundle size report

No bundle size changes (Toolpad)
No bundle size changes

Generated by 🚫 dangerJS against e7de780

[siriwatknp]

Based on the Tailwind CSS docs for disabling preflight

[siriwatknp]

To use the plugin define in the config file (Tailwind v3)

[DiegoAndai]

Only one question on the @mui/material-next-js side, I would request @alexfauquette's review for the docs-infra side.

[DiegoAndai]

Looks good to me from the @mui/material-nextjs side. I'm not approving because we need a review from @mui/docs-infra for the docs side, but feel free to merge when that's done.

[alexfauquette]

Sorry for the delay. Take this approval with a grain of salt, I never used TailwindCSS on a personal project, so I do not know the subtility between v3 and v4 at all

[alexfauquette]

I don't understand how we could get CORS issues. Everything comes from the same origin 🤔

But more security do not hurt