Skip to content

[system] Put styles in CSS sub-layers by default - #49601

Draft
aarongarciah wants to merge 6 commits into
mui:masterfrom
aarongarciah:system-css-sub-layers-default
Draft

aarongarciah wants to merge 6 commits into
mui:masterfrom
aarongarciah:system-css-sub-layers-default

Conversation

@aarongarciah

@aarongarciah aarongarciah commented Oct 28, 2026 •

Copy link
Copy Markdown
Member

Draft for v10: turns on the CSS sub-layers (mui.global, mui.components, mui.theme, mui.custom, mui.sx) by default. cssLayers: false opts out.

Open issues:

  • Theme styleOverrides, styled() and sx now beat the components' state styles (:hover, .Mui-disabled, .Mui-selected).
  • mui is always the lowest layer: other layers (like Tailwind's preflight) beat it, and an order set in the app's CSS can't move it.
  • Unlayered resets like button { padding: 0 } now beat Material UI.
  • jsdom ignores @layer, so style assertions in jsdom tests break.
  • Docs aren't updated yet.

Playground: https://deploy-preview-49601--material-ui.netlify.app/experiments/css-sub-layers/

  • Remove the playground before merging
@code-infra-dashboard

code-infra-dashboard Bot commented Oct 28, 2026 •

Copy link
Copy Markdown

Deploy preview

https://deploy-preview-49601--material-ui.netlify.app/
QR code for https://deploy-preview-49601--material-ui.netlify.app/

Bundle size

Bundle Parsed size Gzip size
@mui/material 🔺+1.89KB(+0.35%) 🔺+708B(+0.45%)
@mui/lab 0B(0.00%) 0B(0.00%)
@mui/private-theming 0B(0.00%) 0B(0.00%)
@mui/system 🔺+1.76KB(+2.53%) 🔺+697B(+2.83%)
@mui/utils 0B(0.00%) 0B(0.00%)

Details of bundle changes

Performance

No regressions in 32 benchmarks · ran 4m 04s · details


Check out the code infra dashboard for more information about this PR.

Theme objects written by hand or built without `createTheme()` don't set it,
and `hasCssLayers()` already treats a missing value as "use `modularCssLayers`".
CI runs the unit tests with --no-isolate, so the setup file runs again for each test file in the same document. The patched appendChild kept the first file's element map while the cleanup cleared the new one, so layer style elements leaked into later files.
@aarongarciah aarongarciah added breaking change Introduces changes that are not backward compatible. scope: system The system, the design tokens / styling foundations used across components. eg. @mui/system with MUI customization: css Design CSS customizability. package: material-ui Specific to Material UI. v10.x labels Oct 28, 2026 — with Claude
- Don't change cached serialized styles when layering them, so a component renders the
  same with `cssLayers: false` after it rendered with layers.
- Layer style objects that start with an `@layer` block.
- Declare the layer order under a ThemeProvider without layers, and for scoped themes.
- Keep the app's own layers, layer order statements and `@import` out of `mui.global`.
- Layer styles that are serialized already in GlobalStyles, and copy them instead of
  changing them in the `enableCssLayer` caches.
- Turn layers off with `modularCssLayers: false`.
@github-actions github-actions Bot added the PR: out-of-date The pull request has merge conflicts and can't be merged. label Oct 28, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

breaking change Introduces changes that are not backward compatible. customization: css Design CSS customizability. package: material-ui Specific to Material UI. PR: out-of-date The pull request has merge conflicts and can't be merged. scope: system The system, the design tokens / styling foundations used across components. eg. @mui/system with MUI v10.x

1 participant