[system] Add `modularCssLayers` theme flag to split styles into multiple CSS layers #46001

siriwatknp · 2025-04-25T06:18:09Z

closes #33012
closes #28911
closes #30536

Docs: https://deploy-preview-46001--material-ui.netlify.app/material-ui/customization/css-layers/
Playground: https://stackblitz.com/edit/6a5ghxfh?file=src%2Findex.tsx

Motivation

By splitting styles into different CSS layers. It eliminates the specificity issue when theming or with sx prop.

For example, customize the padding of the DialogContent using sx prop does not work because the styles of the sx prop cannot beat the default styles from Dialog due to this selector .MuiDialogTitle-root+.css-1foygqf-MuiDialogContent-root:

<Dialog
  open={open}
  onClose={handleClose}
  aria-labelledby="alert-dialog-title"
  aria-describedby="alert-dialog-description"
>
  <DialogTitle id="alert-dialog-title">
    {"Use Google's location service?"}
  </DialogTitle>
  <DialogContent sx={{ pt: 2 }}> <<<<<<<< ❌
    <DialogContentText id="alert-dialog-description">
      Let Google help apps determine location. This means sending anonymous
      location data to Google, even when no apps are running.
    </DialogContentText>
  </DialogContent>
</Dialog>

User will need to increase the specificity in order to override. So if styles are split into different CSS layers @layer, the issue above is gone.

With the same code as above, the generated styles will be:

@layer default {
  .MuiDialogTitle-root+.css-1foygqf-MuiDialogContent-root {
    padding-top: 0px;
  }
}

@layer sx {
  .css-1foygqf-MuiDialogContent-root {
    padding-top: 16px; <<< This wins regardless of the injection order ✅
  }
}

Side benefits

Independent of styles injection order. With modern framework like Next.js evolves, the style injection order might not be straightforward which could produce styles inconsistency for Emotion.

By moving to CSS layers, we don't need to worry about the injection order because CSS will take care of it. Just need to make sure that the layer order is always at the top of the head.

Implementation

When the theme has the flag (modularCssLayers) enabled, Material UI serialize incoming styles (turns object, array, function) to a string and wrap them with @layer layerName. Since the serialized styles come from Emotion, this works perfectly fine.

The styles are split into 5 layers:

@layer global: for styles coming from GlobalStyles component (CssBaseline too)
@layer default: the base styles coming from Material UI components.
@layer theme: the component styles from createTheme().
@layer custom: styles from styled() that does not have Mui name prefix.
@layer sx: styles from the sx prop.

There is no performance downside because the serialization has to be done anyway. When Emotion receive the serialized styles, it will skip the serialization and go through injection process.

Material UI automatically attaches layer order style tag to the document's head first child when modularCssLayers is enabled:

<head>
  <style data-mui-css-layer="…" >@layer mui.global, mui.default, mui.theme, mui.custom, mui.sx;</style>
</head>

Before	After

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

mui-bot · 2025-04-25T06:20:28Z

Netlify deploy preview

docs/data/material/customization/css-layers/css-layers.md

Bundle size report

@mui/material parsed: 🔺+1.72KB^(+0.32%) gzip: 🔺+482B^(+0.31%)
@mui/lab parsed: 🔺+580B^(+0.38%) gzip: 🔺+179B^(+0.36%)
@mui/system parsed: 🔺+1.64KB^(+2.05%) gzip: 🔺+588B^(+1.99%)
@mui/utils parsed: 0B^(0.00%) gzip: 0B^(0.00%)

Details

Show details for 100 more bundles (86 more not shown)

@mui/material/CssBaseline parsed: 🔺+8KB^(+12.66%) gzip: 🔺+3.66KB^(+16.68%)
@mui/material/GlobalStyles parsed: 🔺+8KB^(+13.33%) gzip: 🔺+3.6KB^(+17.36%)
@mui/material/Select parsed: 🔺+907B^(+0.64%) gzip: 🔺+302B^(+0.64%)
@mui/material/TablePagination parsed: 🔺+907B^(+0.52%) gzip: 🔺+288B^(+0.51%)
@mui/material/TextField parsed: 🔺+907B^(+0.59%) gzip: 🔺+271B^(+0.54%)
@mui/material/OutlinedInput parsed: 🔺+862B^(+0.96%) gzip: 🔺+320B^(+1.01%)
@mui/material/NativeSelect parsed: 🔺+860B^(+0.95%) gzip: 🔺+296B^(+0.92%)
@mui/material/FilledInput parsed: 🔺+810B^(+0.92%) gzip: 🔺+313B^(+1.00%)
@mui/material/Input parsed: 🔺+810B^(+0.95%) gzip: 🔺+315B^(+1.02%)
@mui/material/InputBase parsed: 🔺+810B^(+0.98%) gzip: 🔺+276B^(+0.92%)
@mui/material/Radio parsed: 🔺+701B^(+0.74%) gzip: 🔺+199B^(+0.59%)
@mui/material/Checkbox parsed: 🔺+620B^(+0.66%) gzip: 🔺+186B^(+0.55%)
@mui/material/Switch parsed: 🔺+620B^(+0.67%) gzip: 🔺+190B^(+0.58%)
@mui/material/Breadcrumbs parsed: 🔺+610B^(+0.65%) gzip: 🔺+192B^(+0.58%)
@mui/material/SwipeableDrawer parsed: 🔺+595B^(+0.57%) gzip: 🔺+185B^(+0.51%)
@mui/material/Slider parsed: 🔺+583B^(+0.64%) gzip: 🔺+183B^(+0.57%)
@mui/material/Rating parsed: 🔺+579B^(+0.72%) gzip: 🔺+170B^(+0.58%)
@mui/material/IconButton parsed: 🔺+578B^(+0.64%) gzip: 🔺+174B^(+0.54%)
@mui/material/Tab parsed: 🔺+578B^(+0.66%) gzip: 🔺+196B^(+0.63%)
@mui/material/TableSortLabel parsed: 🔺+578B^(+0.64%) gzip: 🔺+192B^(+0.60%)
@mui/material/TabScrollButton parsed: 🔺+578B^(+0.65%) gzip: 🔺+185B^(+0.58%)
@mui/material/AccordionSummary parsed: 🔺+577B^(+0.65%) gzip: 🔺+194B^(+0.61%)
@mui/material/BottomNavigationAction parsed: 🔺+577B^(+0.66%) gzip: 🔺+195B^(+0.62%)
@mui/material/ButtonBase parsed: 🔺+577B^(+0.69%) gzip: 🔺+181B^(+0.60%)
@mui/material/CardActionArea parsed: 🔺+577B^(+0.66%) gzip: 🔺+190B^(+0.61%)
@mui/material/Collapse parsed: 🔺+577B^(+0.75%) gzip: 🔺+157B^(+0.56%)
@mui/material/Fab parsed: 🔺+577B^(+0.66%) gzip: 🔺+193B^(+0.62%)
@mui/material/ListItemButton parsed: 🔺+577B^(+0.66%) gzip: 🔺+193B^(+0.62%)
@mui/material/MenuItem parsed: 🔺+577B^(+0.66%) gzip: 🔺+202B^(+0.64%)
@mui/material/StepContent parsed: 🔺+577B^(+0.72%) gzip: 🔺+179B^(+0.62%)
@mui/material/ToggleButton parsed: 🔺+577B^(+0.66%) gzip: 🔺+200B^(+0.64%)
@mui/lab/LoadingButton parsed: 🔺+576B^(+0.59%) gzip: 🔺+188B^(+0.56%)
@mui/lab/Masonry parsed: 🔺+576B^(+0.79%) gzip: 🔺+193B^(+0.73%)
@mui/lab/TabList parsed: 🔺+576B^(+0.57%) gzip: 🔺+199B^(+0.55%)
@mui/material/Alert parsed: 🔺+576B^(+0.57%) gzip: 🔺+179B^(+0.51%)
@mui/material/Badge parsed: 🔺+576B^(+0.75%) gzip: 🔺+183B^(+0.67%)
@mui/material/Button parsed: 🔺+576B^(+0.59%) gzip: 🔺+192B^(+0.58%)
@mui/material/FormControlLabel parsed: 🔺+576B^(+0.76%) gzip: 🔺+162B^(+0.59%)
@mui/material/StepButton parsed: 🔺+576B^(+0.61%) gzip: 🔺+192B^(+0.58%)
@mui/material/StepLabel parsed: 🔺+576B^(+0.75%) gzip: 🔺+194B^(+0.70%)
@mui/material/Tabs parsed: 🔺+576B^(+0.57%) gzip: 🔺+190B^(+0.53%)
@mui/lab/TabPanel parsed: 🔺+575B^(+0.83%) gzip: 🔺+171B^(+0.69%)
@mui/lab/Timeline parsed: 🔺+575B^(+0.83%) gzip: 🔺+167B^(+0.67%)
@mui/lab/TimelineConnector parsed: 🔺+575B^(+0.84%) gzip: 🔺+165B^(+0.67%)
@mui/lab/TimelineContent parsed: 🔺+575B^(+0.79%) gzip: 🔺+162B^(+0.62%)
@mui/lab/TimelineDot parsed: 🔺+575B^(+0.83%) gzip: 🔺+177B^(+0.71%)
@mui/lab/TimelineItem parsed: 🔺+575B^(+0.82%) gzip: 🔺+177B^(+0.70%)
@mui/lab/TimelineOppositeContent parsed: 🔺+575B^(+0.79%) gzip: 🔺+170B^(+0.65%)
@mui/lab/TimelineSeparator parsed: 🔺+575B^(+0.84%) gzip: 🔺+165B^(+0.67%)
@mui/material/Accordion parsed: 🔺+575B^(+0.69%) gzip: 🔺+180B^(+0.60%)
@mui/material/AccordionActions parsed: 🔺+575B^(+0.84%) gzip: 🔺+184B^(+0.74%)
@mui/material/AccordionDetails parsed: 🔺+575B^(+0.84%) gzip: 🔺+185B^(+0.74%)
@mui/material/AlertTitle parsed: 🔺+575B^(+0.80%) gzip: 🔺+173B^(+0.67%)
@mui/material/AppBar parsed: 🔺+575B^(+0.78%) gzip: 🔺+187B^(+0.71%)
@mui/material/Avatar parsed: 🔺+575B^(+0.76%) gzip: 🔺+172B^(+0.63%)
@mui/material/AvatarGroup parsed: 🔺+575B^(+0.75%) gzip: 🔺+174B^(+0.62%)
@mui/material/Backdrop parsed: 🔺+575B^(+0.74%) gzip: 🔺+183B^(+0.66%)
@mui/material/BottomNavigation parsed: 🔺+575B^(+0.83%) gzip: 🔺+175B^(+0.70%)
@mui/material/ButtonGroup parsed: 🔺+575B^(+0.77%) gzip: 🔺+190B^(+0.73%)
@mui/material/Card parsed: 🔺+575B^(+0.81%) gzip: 🔺+163B^(+0.64%)
@mui/material/CardActions parsed: 🔺+575B^(+0.84%) gzip: 🔺+182B^(+0.73%)
@mui/material/CardContent parsed: 🔺+575B^(+0.84%) gzip: 🔺+185B^(+0.74%)
@mui/material/CardHeader parsed: 🔺+575B^(+0.76%) gzip: 🔺+176B^(+0.65%)
@mui/material/CardMedia parsed: 🔺+575B^(+0.83%) gzip: 🔺+183B^(+0.73%)
@mui/material/Chip parsed: 🔺+575B^(+0.59%) gzip: 🔺+171B^(+0.50%)
@mui/material/CircularProgress parsed: 🔺+575B^(+0.77%) gzip: 🔺+186B^(+0.69%)
@mui/material/Container parsed: 🔺+575B^(+0.82%) gzip: 🔺+185B^(+0.73%)
@mui/material/Dialog parsed: 🔺+575B^(+0.61%) gzip: 🔺+191B^(+0.57%)
@mui/material/DialogActions parsed: 🔺+575B^(+0.84%) gzip: 🔺+181B^(+0.72%)
@mui/material/DialogContent parsed: 🔺+575B^(+0.83%) gzip: 🔺+179B^(+0.71%)
@mui/material/DialogContentText parsed: 🔺+575B^(+0.80%) gzip: 🔺+182B^(+0.70%)
@mui/material/DialogTitle parsed: 🔺+575B^(+0.80%) gzip: 🔺+177B^(+0.68%)
@mui/material/Divider parsed: 🔺+575B^(+0.80%) gzip: 🔺+184B^(+0.71%)
@mui/material/Drawer parsed: 🔺+575B^(+0.59%) gzip: 🔺+183B^(+0.53%)
@mui/material/FormGroup parsed: 🔺+575B^(+0.83%) gzip: 🔺+181B^(+0.72%)
@mui/material/FormHelperText parsed: 🔺+575B^(+0.82%) gzip: 🔺+169B^(+0.66%)
@mui/material/FormLabel parsed: 🔺+575B^(+0.82%) gzip: 🔺+180B^(+0.70%)
@mui/material/Grid parsed: 🔺+575B^(+0.77%) gzip: 🔺+169B^(+0.63%)
@mui/material/GridLegacy parsed: 🔺+575B^(+0.78%) gzip: 🔺+174B^(+0.66%)
@mui/material/Icon parsed: 🔺+575B^(+0.82%) gzip: 🔺+183B^(+0.72%)
@mui/material/ImageList parsed: 🔺+575B^(+0.83%) gzip: 🔺+175B^(+0.70%)
@mui/material/ImageListItem parsed: 🔺+575B^(+0.82%) gzip: 🔺+196B^(+0.77%)
@mui/material/ImageListItemBar parsed: 🔺+575B^(+0.81%) gzip: 🔺+165B^(+0.64%)
@mui/material/InputAdornment parsed: 🔺+575B^(+0.79%) gzip: 🔺+174B^(+0.66%)
@mui/material/InputLabel parsed: 🔺+575B^(+0.78%) gzip: 🔺+168B^(+0.64%)
@mui/material/LinearProgress parsed: 🔺+575B^(+0.73%) gzip: 🔺+208B^(+0.76%)
@mui/material/Link parsed: 🔺+575B^(+0.77%) gzip: 🔺+188B^(+0.70%)
@mui/material/List parsed: 🔺+575B^(+0.83%) gzip: 🔺+174B^(+0.69%)
@mui/material/ListItem parsed: 🔺+575B^(+0.79%) gzip: 🔺+168B^(+0.64%)
@mui/material/ListItemAvatar parsed: 🔺+575B^(+0.84%) gzip: 🔺+190B^(+0.76%)
@mui/material/ListItemIcon parsed: 🔺+575B^(+0.83%) gzip: 🔺+185B^(+0.74%)
@mui/material/ListItemSecondaryAction parsed: 🔺+575B^(+0.83%) gzip: 🔺+188B^(+0.75%)
@mui/material/ListItemText parsed: 🔺+575B^(+0.76%) gzip: 🔺+177B^(+0.65%)
@mui/material/ListSubheader parsed: 🔺+575B^(+0.82%) gzip: 🔺+182B^(+0.72%)
@mui/material/MenuList parsed: 🔺+575B^(+0.80%) gzip: 🔺+185B^(+0.70%)
@mui/material/MobileStepper parsed: 🔺+575B^(+0.67%) gzip: 🔺+181B^(+0.61%)
@mui/material/Modal parsed: 🔺+575B^(+0.65%) gzip: 🔺+183B^(+0.58%)
@mui/material/Pagination parsed: 🔺+575B^(+0.59%) gzip: 🔺+184B^(+0.54%)
@mui/material/PaginationItem parsed: 🔺+575B^(+0.60%) gzip: 🔺+161B^(+0.48%)
@mui/material/Paper parsed: 🔺+575B^(+0.82%) gzip: 🔺+174B^(+0.68%)

Details of bundle changes

Generated by 🚫 dangerJS against c170244

…/mui-css-layer

…i into feat/mui-css-layer

…/mui-css-layer

docs/data/material/customization/css-layers/css-layers.md

…/mui-css-layer

…i into feat/mui-css-layer

docs/data/material/customization/css-layers/css-layers.md

mapache-salvaje

Nice work @siriwatknp ! Very cool feature!

docs/data/material/customization/css-layers/css-layers.md

Co-authored-by: mapache-salvaje <71297412+mapache-salvaje@users.noreply.github.com> Co-authored-by: Marija Najdova <mnajdova@gmail.com> Signed-off-by: Siriwat K <siriwatkunaporn@gmail.com>

…/mui-css-layer

mapache-salvaje

A few more suggestions here to sharpen the Caveats section but otherwise I think the doc's ready to go!

docs/data/material/customization/css-layers/css-layers.md

Co-authored-by: mapache-salvaje <71297412+mapache-salvaje@users.noreply.github.com> Signed-off-by: Siriwat K <siriwatkunaporn@gmail.com>

…ple CSS layers (mui#46001) 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

add theme and sx css layer

25ed058

siriwatknp added the scope: system The system, the design tokens / styling foundations used across components. eg. @mui/system with MUI label Apr 25, 2025

siriwatknp added 4 commits April 25, 2025 14:15

add experimental_dedicatedCssLayer option

650c5be

fix nested rules

072a318

wip

4663f11

wip

fd97877

siriwatknp mentioned this pull request Apr 29, 2025

[DataGrid] Agnostic styling mui/mui-x#16677

Draft

siriwatknp added 22 commits May 7, 2025 13:11

Merge branch 'master' of https://github.com/mui/material-ui into feat…

f5560be

…/mui-css-layer

restore non-working approach

32ab754

poc nested css layers

ddd1bdb

Merge branch 'master' into feat/mui-css-layer

222fc84

prevent recursive nesting

aaf9ac7

rename to experimental_modularCssLayers

1d2011a

Merge branch 'feat/mui-css-layer' of github.com:siriwatknp/material-u…

1955562

…i into feat/mui-css-layer

add layer custom and rename base to default

837d9f6

revert unnecessary

ae48dd6

remove experiment

c6ac569

Merge branch 'master' of https://github.com/mui/material-ui into feat…

63926d7

…/mui-css-layer

Merge branch 'master' of https://github.com/mui/material-ui into feat…

ce9d9c0

…/mui-css-layer

revert

8395602

Merge branch 'master' of https://github.com/mui/material-ui into feat…

48699bd

…/mui-css-layer

add comment

7722bca

add test

a4f2db9

update test

9ea768d

add global layer to global styles

92d1e0e

Merge branch 'master' of https://github.com/mui/material-ui into feat…

6843a52

…/mui-css-layer

update docs layer config

748f822

skip nested layer for non serialized

e1161fb

add name to all components

7cb2bd4

siriwatknp commented Jun 5, 2025

View reviewed changes

docs/data/material/customization/css-layers/css-layers.md Outdated Show resolved Hide resolved

mnajdova reviewed Jun 5, 2025

View reviewed changes

docs/data/material/customization/css-layers/css-layers.md Outdated Show resolved Hide resolved

siriwatknp added 5 commits June 6, 2025 13:30

Merge branch 'master' of https://github.com/mui/material-ui into feat…

aaaf17a

…/mui-css-layer

rename mui.default to mui.components

ebedbad

Merge branch 'feat/mui-css-layer' of github.com:siriwatknp/material-u…

09baca4

…i into feat/mui-css-layer

update docs

09ecf8c

remove experimental prefix

d3e69c5

siriwatknp changed the title ~~[system] Add experimental_modularCssLayers theme flag to split styles into multiple CSS layers~~ [system] Add modularCssLayers theme flag to split styles into multiple CSS layers Jun 6, 2025

siriwatknp mentioned this pull request Jun 6, 2025

[material-nextjs][system] Backport CSS layers to v6 #46283

Merged

1 task

mnajdova mentioned this pull request Jun 7, 2025

[poc] Support a version of Material UI without CSS in JS #44407

Draft

5 tasks

mnajdova reviewed Jun 7, 2025

View reviewed changes

docs/data/material/customization/css-layers/css-layers.md Show resolved Hide resolved

mapache-salvaje reviewed Jun 10, 2025

View reviewed changes

siriwatknp and others added 4 commits June 11, 2025 10:07

Apply suggestions from code review

709a2e8

Co-authored-by: mapache-salvaje <71297412+mapache-salvaje@users.noreply.github.com> Co-authored-by: Marija Najdova <mnajdova@gmail.com> Signed-off-by: Siriwat K <siriwatkunaporn@gmail.com>

add caveat

52caf86

Merge branch 'master' of https://github.com/mui/material-ui into feat…

5f625ca

…/mui-css-layer

update caveat

2c1eb5b

siriwatknp requested review from DiegoAndai, mapache-salvaje and mnajdova June 11, 2025 05:02

siriwatknp added 2 commits June 11, 2025 12:04

fix grammar

13f7c28

fix lint

2cdbc82

mapache-salvaje approved these changes Jun 11, 2025

View reviewed changes

docs/data/material/customization/css-layers/css-layers.md Outdated Show resolved Hide resolved

docs/data/material/customization/css-layers/css-layers.md Outdated Show resolved Hide resolved

docs/data/material/customization/css-layers/css-layers.md Outdated Show resolved Hide resolved

DiegoAndai approved these changes Jun 11, 2025

View reviewed changes

Apply suggestions from code review

c170244

Co-authored-by: mapache-salvaje <71297412+mapache-salvaje@users.noreply.github.com> Signed-off-by: Siriwat K <siriwatkunaporn@gmail.com>

siriwatknp merged commit 37d7020 into mui:master Jun 12, 2025
23 checks passed

siriwatknp mentioned this pull request Jun 12, 2025

[material-nextjs][system] Backport CSS layers to v5 #46320

Merged

1 task

Uh oh!

[system] Add modularCssLayers theme flag to split styles into multiple CSS layers #46001

[system] Add modularCssLayers theme flag to split styles into multiple CSS layers #46001

Uh oh!

Conversation

siriwatknp commented Apr 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Side benefits

Implementation

Uh oh!

mui-bot commented Apr 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Netlify deploy preview

Bundle size report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mapache-salvaje left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mapache-salvaje left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

[system] Add `modularCssLayers` theme flag to split styles into multiple CSS layers #46001

[system] Add `modularCssLayers` theme flag to split styles into multiple CSS layers #46001

siriwatknp commented Apr 25, 2025 •

edited

Loading

mui-bot commented Apr 25, 2025 •

edited

Loading