@mui/system 6.4.12 → 6.5.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # [Versions](https://mui.com/versions/)
 
+## 6.5.0
+
+<!-- generated comparing v6.4.12..v6.x -->
+
+_Jul 2, 2025_
+
+A big thanks to the 2 contributors who made this release possible.
+
+CSS layers make it easier to override styles by splitting a single style sheet into multiple layers.
+To learn more, check out the [CSS layers documentation](https://v6.mui.com/material-ui/customization/css-layers/).
+
+### `@mui/material@6.5.0`
+
+- [Dialog] Add codemod for deprecated props (#46335) @sai6855
+
+### `@mui/system@6.5.0`
+
+- Backport CSS layers feature from v7 (#46283) @siriwatknp
+
+### `@mui/material-nextjs@6.5.0`
+
+- Backport CSS layers feature from v7 (#46283) @siriwatknp
+
+### Docs
+
+- Add ListItemButton to make the deprecation clear (#46357) @sai6855
+
+All contributors of this release in alphabetical order: @sai6855, @siriwatknp
+
 ## 6.4.12
 
 <!-- generated comparing v6.4.11..v6.x -->

package/GlobalStyles/GlobalStyles.js

@@ -12,13 +12,37 @@ var _propTypes = _interopRequireDefault(require("prop-types"));
 var _styledEngine = require("@mui/styled-engine");
 var _useTheme = _interopRequireDefault(require("../useTheme"));
 var _jsxRuntime = require("react/jsx-runtime");
+function wrapGlobalLayer(styles) {
+  const serialized = (0, _styledEngine.internal_serializeStyles)(styles);
+  if (styles !== serialized && serialized.styles) {
+    if (!serialized.styles.match(/^@layer\s+[^{]*$/)) {
+      // If the styles are not already wrapped in a layer, wrap them in a global layer.
+      serialized.styles = `@layer global{${serialized.styles}}`;
+    }
+    return serialized;
+  }
+  return styles;
+}
 function GlobalStyles({
   styles,
   themeId,
   defaultTheme = {}
 }) {
   const upperTheme = (0, _useTheme.default)(defaultTheme);
-  const globalStyles = typeof styles === 'function' ? styles(themeId ? upperTheme[themeId] || upperTheme : upperTheme) : styles;
+  const resolvedTheme = themeId ? upperTheme[themeId] || upperTheme : upperTheme;
+  let globalStyles = typeof styles === 'function' ? styles(resolvedTheme) : styles;
+  if (resolvedTheme.modularCssLayers) {
+    if (Array.isArray(globalStyles)) {
+      globalStyles = globalStyles.map(styleArg => {
+        if (typeof styleArg === 'function') {
+          return wrapGlobalLayer(styleArg(resolvedTheme));
+        }
+        return wrapGlobalLayer(styleArg);
+      });
+    } else {
+      globalStyles = wrapGlobalLayer(globalStyles);
+    }
+  }
   return /*#__PURE__*/(0, _jsxRuntime.jsx)(_styledEngine.GlobalStyles, {
     styles: globalStyles
   });

package/ThemeProvider/ThemeProvider.js

@@ -15,6 +15,7 @@ var _styledEngine = require("@mui/styled-engine");
 var _useThemeWithoutDefault = _interopRequireDefault(require("../useThemeWithoutDefault"));
 var _RtlProvider = _interopRequireDefault(require("../RtlProvider"));
 var _DefaultPropsProvider = _interopRequireDefault(require("../DefaultPropsProvider"));
+var _useLayerOrder = _interopRequireDefault(require("./useLayerOrder"));
 var _jsxRuntime = require("react/jsx-runtime");
 const EMPTY_THEME = {};
 function useThemeScoping(themeId, upperTheme, localTheme, isPrivate = false) {
@@ -66,15 +67,16 @@ function ThemeProvider(props) {
   const engineTheme = useThemeScoping(themeId, upperTheme, localTheme);
   const privateTheme = useThemeScoping(themeId, upperPrivateTheme, localTheme, true);
   const rtlValue = (themeId ? engineTheme[themeId] : engineTheme).direction === 'rtl';
+  const layerOrder = (0, _useLayerOrder.default)(engineTheme);
   return /*#__PURE__*/(0, _jsxRuntime.jsx)(_privateTheming.ThemeProvider, {
     theme: privateTheme,
     children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_styledEngine.ThemeContext.Provider, {
       value: engineTheme,
       children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_RtlProvider.default, {
         value: rtlValue,
-        children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_DefaultPropsProvider.default, {
+        children: /*#__PURE__*/(0, _jsxRuntime.jsxs)(_DefaultPropsProvider.default, {
           value: themeId ? engineTheme[themeId].components : engineTheme.components,
-          children: children
+          children: [layerOrder, children]
         })
       })
     })

package/ThemeProvider/useLayerOrder.d.ts

@@ -0,0 +1,8 @@
+import * as React from 'react';
+/**
+ * This hook returns a `GlobalStyles` component that sets the CSS layer order (for server-side rendering).
+ * Then on client-side, it injects the CSS layer order into the document head to ensure that the layer order is always present first before other Emotion styles.
+ */
+export default function useLayerOrder(theme: {
+    modularCssLayers?: boolean | string;
+}): React.JSX.Element | null;

package/ThemeProvider/useLayerOrder.js

@@ -0,0 +1,58 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault").default;
+var _interopRequireWildcard = require("@babel/runtime/helpers/interopRequireWildcard").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = useLayerOrder;
+var React = _interopRequireWildcard(require("react"));
+var _useEnhancedEffect = _interopRequireDefault(require("@mui/utils/useEnhancedEffect"));
+var _useId = _interopRequireDefault(require("@mui/utils/useId"));
+var _GlobalStyles = _interopRequireDefault(require("../GlobalStyles"));
+var _useThemeWithoutDefault = _interopRequireDefault(require("../useThemeWithoutDefault"));
+var _jsxRuntime = require("react/jsx-runtime");
+/**
+ * This hook returns a `GlobalStyles` component that sets the CSS layer order (for server-side rendering).
+ * Then on client-side, it injects the CSS layer order into the document head to ensure that the layer order is always present first before other Emotion styles.
+ */function useLayerOrder(theme) {
+  const upperTheme = (0, _useThemeWithoutDefault.default)();
+  const id = (0, _useId.default)() || '';
+  const {
+    modularCssLayers
+  } = theme;
+  let layerOrder = 'mui.global, mui.components, mui.theme, mui.custom, mui.sx';
+  if (!modularCssLayers || upperTheme !== null) {
+    // skip this hook if upper theme exists.
+    layerOrder = '';
+  } else if (typeof modularCssLayers === 'string') {
+    layerOrder = modularCssLayers.replace(/mui(?!\.)/g, layerOrder);
+  } else {
+    layerOrder = `@layer ${layerOrder};`;
+  }
+  (0, _useEnhancedEffect.default)(() => {
+    const head = document.querySelector('head');
+    if (!head) {
+      return;
+    }
+    const firstChild = head.firstChild;
+    if (layerOrder) {
+      // Only insert if first child doesn't have data-mui-layer-order attribute
+      if (firstChild && firstChild.hasAttribute?.('data-mui-layer-order') && firstChild.getAttribute('data-mui-layer-order') === id) {
+        return;
+      }
+      const styleElement = document.createElement('style');
+      styleElement.setAttribute('data-mui-layer-order', id);
+      styleElement.textContent = layerOrder;
+      head.prepend(styleElement);
+    } else {
+      head.querySelector(`style[data-mui-layer-order="${id}"]`)?.remove();
+    }
+  }, [layerOrder, id]);
+  if (!layerOrder) {
+    return null;
+  }
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_GlobalStyles.default, {
+    styles: layerOrder
+  });
+}

package/createStyled/createStyled.js

@@ -25,6 +25,13 @@ const systemDefaultTheme = exports.systemDefaultTheme = (0, _createTheme.default
 function shouldForwardProp(prop) {
   return prop !== 'ownerState' && prop !== 'theme' && prop !== 'sx' && prop !== 'as';
 }
+function shallowLayer(serialized, layerName) {
+  if (layerName && serialized && typeof serialized === 'object' && serialized.styles && !serialized.styles.startsWith('@layer') // only add the layer if it is not already there.
+  ) {
+    serialized.styles = `@layer ${layerName}{${String(serialized.styles)}}`;
+  }
+  return serialized;
+}
 function defaultOverridesResolver(slot) {
   if (!slot) {
     return null;
@@ -34,7 +41,7 @@ function defaultOverridesResolver(slot) {
 function attachTheme(props, themeId, defaultTheme) {
   props.theme = isObjectEmpty(props.theme) ? defaultTheme : props.theme[themeId] || props.theme;
 }
-function processStyle(props, style) {
+function processStyle(props, style, layerName) {
   /*
    * Style types:
    *  - null/undefined
@@ -46,27 +53,27 @@ function processStyle(props, style) {
 
   const resolvedStyle = typeof style === 'function' ? style(props) : style;
   if (Array.isArray(resolvedStyle)) {
-    return resolvedStyle.flatMap(subStyle => processStyle(props, subStyle));
+    return resolvedStyle.flatMap(subStyle => processStyle(props, subStyle, layerName));
   }
   if (Array.isArray(resolvedStyle?.variants)) {
     let rootStyle;
     if (resolvedStyle.isProcessed) {
-      rootStyle = resolvedStyle.style;
+      rootStyle = layerName ? shallowLayer(resolvedStyle.style, layerName) : resolvedStyle.style;
     } else {
       const {
         variants,
         ...otherStyles
       } = resolvedStyle;
-      rootStyle = otherStyles;
+      rootStyle = layerName ? shallowLayer((0, _styledEngine.internal_serializeStyles)(otherStyles), layerName) : otherStyles;
     }
-    return processStyleVariants(props, resolvedStyle.variants, [rootStyle]);
+    return processStyleVariants(props, resolvedStyle.variants, [rootStyle], layerName);
   }
   if (resolvedStyle?.isProcessed) {
-    return resolvedStyle.style;
+    return layerName ? shallowLayer((0, _styledEngine.internal_serializeStyles)(resolvedStyle.style), layerName) : resolvedStyle.style;
   }
-  return resolvedStyle;
+  return layerName ? shallowLayer((0, _styledEngine.internal_serializeStyles)(resolvedStyle), layerName) : resolvedStyle;
 }
-function processStyleVariants(props, variants, results = []) {
+function processStyleVariants(props, variants, results = [], layerName = undefined) {
   let mergedState; // We might not need it, initialized lazily
 
   variantLoop: for (let i = 0; i < variants.length; i += 1) {
@@ -93,9 +100,9 @@ function processStyleVariants(props, variants, results = []) {
         ...props.ownerState,
         ownerState: props.ownerState
       });
-      results.push(variant.style(mergedState));
+      results.push(layerName ? shallowLayer((0, _styledEngine.internal_serializeStyles)(variant.style(mergedState)), layerName) : variant.style(mergedState));
     } else {
-      results.push(variant.style);
+      results.push(layerName ? shallowLayer((0, _styledEngine.internal_serializeStyles)(variant.style), layerName) : variant.style);
     }
   }
   return results;
@@ -124,6 +131,7 @@ function createStyled(input = {}) {
       overridesResolver = defaultOverridesResolver(lowercaseFirstLetter(componentSlot)),
       ...options
     } = inputOptions;
+    const layerName = componentName && componentName.startsWith('Mui') || !!componentSlot ? 'components' : 'custom';
 
     // if skipVariantsResolver option is defined, take the value, otherwise, true for root and false for other slots.
     const skipVariantsResolver = inputSkipVariantsResolver !== undefined ? inputSkipVariantsResolver :
@@ -160,16 +168,16 @@ function createStyled(input = {}) {
       }
       if (typeof style === 'function') {
         return function styleFunctionProcessor(props) {
-          return processStyle(props, style);
+          return processStyle(props, style, props.theme.modularCssLayers ? layerName : undefined);
         };
       }
       if ((0, _deepmerge.isPlainObject)(style)) {
         const serialized = (0, _preprocessStyles.default)(style);
-        if (!serialized.variants) {
-          return serialized.style;
-        }
         return function styleObjectProcessor(props) {
-          return processStyle(props, serialized);
+          if (!serialized.variants) {
+            return props.theme.modularCssLayers ? shallowLayer(serialized.style, layerName) : serialized.style;
+          }
+          return processStyle(props, serialized, props.theme.modularCssLayers ? layerName : undefined);
         };
       }
       return style;
@@ -194,7 +202,7 @@ function createStyled(input = {}) {
           // TODO: v7 remove iteration and use `resolveStyleArg(styleOverrides[slot])` directly
           // eslint-disable-next-line guard-for-in
           for (const slotKey in styleOverrides) {
-            resolvedStyleOverrides[slotKey] = processStyle(props, styleOverrides[slotKey]);
+            resolvedStyleOverrides[slotKey] = processStyle(props, styleOverrides[slotKey], props.theme.modularCssLayers ? 'theme' : undefined);
           }
           return overridesResolver(props, resolvedStyleOverrides);
         });
@@ -206,7 +214,7 @@ function createStyled(input = {}) {
           if (!themeVariants) {
             return null;
           }
-          return processStyleVariants(props, themeVariants);
+          return processStyleVariants(props, themeVariants, [], props.theme.modularCssLayers ? 'theme' : undefined);
         });
       }
       if (!skipSx) {

package/esm/GlobalStyles/GlobalStyles.js

@@ -2,16 +2,40 @@
 
 import * as React from 'react';
 import PropTypes from 'prop-types';
-import { GlobalStyles as MuiGlobalStyles } from '@mui/styled-engine';
+import { GlobalStyles as MuiGlobalStyles, internal_serializeStyles as serializeStyles } from '@mui/styled-engine';
 import useTheme from "../useTheme/index.js";
 import { jsx as _jsx } from "react/jsx-runtime";
+function wrapGlobalLayer(styles) {
+  const serialized = serializeStyles(styles);
+  if (styles !== serialized && serialized.styles) {
+    if (!serialized.styles.match(/^@layer\s+[^{]*$/)) {
+      // If the styles are not already wrapped in a layer, wrap them in a global layer.
+      serialized.styles = `@layer global{${serialized.styles}}`;
+    }
+    return serialized;
+  }
+  return styles;
+}
 function GlobalStyles({
   styles,
   themeId,
   defaultTheme = {}
 }) {
   const upperTheme = useTheme(defaultTheme);
-  const globalStyles = typeof styles === 'function' ? styles(themeId ? upperTheme[themeId] || upperTheme : upperTheme) : styles;
+  const resolvedTheme = themeId ? upperTheme[themeId] || upperTheme : upperTheme;
+  let globalStyles = typeof styles === 'function' ? styles(resolvedTheme) : styles;
+  if (resolvedTheme.modularCssLayers) {
+    if (Array.isArray(globalStyles)) {
+      globalStyles = globalStyles.map(styleArg => {
+        if (typeof styleArg === 'function') {
+          return wrapGlobalLayer(styleArg(resolvedTheme));
+        }
+        return wrapGlobalLayer(styleArg);
+      });
+    } else {
+      globalStyles = wrapGlobalLayer(globalStyles);
+    }
+  }
   return /*#__PURE__*/_jsx(MuiGlobalStyles, {
     styles: globalStyles
   });

package/esm/ThemeProvider/ThemeProvider.js

@@ -8,7 +8,8 @@ import { ThemeContext as StyledEngineThemeContext } from '@mui/styled-engine';
 import useThemeWithoutDefault from "../useThemeWithoutDefault/index.js";
 import RtlProvider from "../RtlProvider/index.js";
 import DefaultPropsProvider from "../DefaultPropsProvider/index.js";
-import { jsx as _jsx } from "react/jsx-runtime";
+import useLayerOrder from "./useLayerOrder.js";
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
 const EMPTY_THEME = {};
 function useThemeScoping(themeId, upperTheme, localTheme, isPrivate = false) {
   return React.useMemo(() => {
@@ -59,15 +60,16 @@ function ThemeProvider(props) {
   const engineTheme = useThemeScoping(themeId, upperTheme, localTheme);
   const privateTheme = useThemeScoping(themeId, upperPrivateTheme, localTheme, true);
   const rtlValue = (themeId ? engineTheme[themeId] : engineTheme).direction === 'rtl';
+  const layerOrder = useLayerOrder(engineTheme);
   return /*#__PURE__*/_jsx(MuiThemeProvider, {
     theme: privateTheme,
     children: /*#__PURE__*/_jsx(StyledEngineThemeContext.Provider, {
       value: engineTheme,
       children: /*#__PURE__*/_jsx(RtlProvider, {
         value: rtlValue,
-        children: /*#__PURE__*/_jsx(DefaultPropsProvider, {
+        children: /*#__PURE__*/_jsxs(DefaultPropsProvider, {
           value: themeId ? engineTheme[themeId].components : engineTheme.components,
-          children: children
+          children: [layerOrder, children]
         })
       })
     })

package/esm/ThemeProvider/useLayerOrder.js

@@ -0,0 +1,52 @@
+import * as React from 'react';
+import useEnhancedEffect from '@mui/utils/useEnhancedEffect';
+import useId from '@mui/utils/useId';
+import GlobalStyles from "../GlobalStyles/index.js";
+import useThemeWithoutDefault from "../useThemeWithoutDefault/index.js";
+
+/**
+ * This hook returns a `GlobalStyles` component that sets the CSS layer order (for server-side rendering).
+ * Then on client-side, it injects the CSS layer order into the document head to ensure that the layer order is always present first before other Emotion styles.
+ */
+import { jsx as _jsx } from "react/jsx-runtime";
+export default function useLayerOrder(theme) {
+  const upperTheme = useThemeWithoutDefault();
+  const id = useId() || '';
+  const {
+    modularCssLayers
+  } = theme;
+  let layerOrder = 'mui.global, mui.components, mui.theme, mui.custom, mui.sx';
+  if (!modularCssLayers || upperTheme !== null) {
+    // skip this hook if upper theme exists.
+    layerOrder = '';
+  } else if (typeof modularCssLayers === 'string') {
+    layerOrder = modularCssLayers.replace(/mui(?!\.)/g, layerOrder);
+  } else {
+    layerOrder = `@layer ${layerOrder};`;
+  }
+  useEnhancedEffect(() => {
+    const head = document.querySelector('head');
+    if (!head) {
+      return;
+    }
+    const firstChild = head.firstChild;
+    if (layerOrder) {
+      // Only insert if first child doesn't have data-mui-layer-order attribute
+      if (firstChild && firstChild.hasAttribute?.('data-mui-layer-order') && firstChild.getAttribute('data-mui-layer-order') === id) {
+        return;
+      }
+      const styleElement = document.createElement('style');
+      styleElement.setAttribute('data-mui-layer-order', id);
+      styleElement.textContent = layerOrder;
+      head.prepend(styleElement);
+    } else {
+      head.querySelector(`style[data-mui-layer-order="${id}"]`)?.remove();
+    }
+  }, [layerOrder, id]);
+  if (!layerOrder) {
+    return null;
+  }
+  return /*#__PURE__*/_jsx(GlobalStyles, {
+    styles: layerOrder
+  });
+}

package/esm/createStyled/createStyled.js

@@ -1,4 +1,4 @@
-import styledEngineStyled, { internal_mutateStyles as mutateStyles } from '@mui/styled-engine';
+import styledEngineStyled, { internal_mutateStyles as mutateStyles, internal_serializeStyles as serializeStyles } from '@mui/styled-engine';
 import { isPlainObject } from '@mui/utils/deepmerge';
 import capitalize from '@mui/utils/capitalize';
 import getDisplayName from '@mui/utils/getDisplayName';
@@ -16,6 +16,13 @@ export const systemDefaultTheme = createTheme();
 export function shouldForwardProp(prop) {
   return prop !== 'ownerState' && prop !== 'theme' && prop !== 'sx' && prop !== 'as';
 }
+function shallowLayer(serialized, layerName) {
+  if (layerName && serialized && typeof serialized === 'object' && serialized.styles && !serialized.styles.startsWith('@layer') // only add the layer if it is not already there.
+  ) {
+    serialized.styles = `@layer ${layerName}{${String(serialized.styles)}}`;
+  }
+  return serialized;
+}
 function defaultOverridesResolver(slot) {
   if (!slot) {
     return null;
@@ -25,7 +32,7 @@ function defaultOverridesResolver(slot) {
 function attachTheme(props, themeId, defaultTheme) {
   props.theme = isObjectEmpty(props.theme) ? defaultTheme : props.theme[themeId] || props.theme;
 }
-function processStyle(props, style) {
+function processStyle(props, style, layerName) {
   /*
    * Style types:
    *  - null/undefined
@@ -37,27 +44,27 @@ function processStyle(props, style) {
 
   const resolvedStyle = typeof style === 'function' ? style(props) : style;
   if (Array.isArray(resolvedStyle)) {
-    return resolvedStyle.flatMap(subStyle => processStyle(props, subStyle));
+    return resolvedStyle.flatMap(subStyle => processStyle(props, subStyle, layerName));
   }
   if (Array.isArray(resolvedStyle?.variants)) {
     let rootStyle;
     if (resolvedStyle.isProcessed) {
-      rootStyle = resolvedStyle.style;
+      rootStyle = layerName ? shallowLayer(resolvedStyle.style, layerName) : resolvedStyle.style;
     } else {
       const {
         variants,
         ...otherStyles
       } = resolvedStyle;
-      rootStyle = otherStyles;
+      rootStyle = layerName ? shallowLayer(serializeStyles(otherStyles), layerName) : otherStyles;
     }
-    return processStyleVariants(props, resolvedStyle.variants, [rootStyle]);
+    return processStyleVariants(props, resolvedStyle.variants, [rootStyle], layerName);
   }
   if (resolvedStyle?.isProcessed) {
-    return resolvedStyle.style;
+    return layerName ? shallowLayer(serializeStyles(resolvedStyle.style), layerName) : resolvedStyle.style;
   }
-  return resolvedStyle;
+  return layerName ? shallowLayer(serializeStyles(resolvedStyle), layerName) : resolvedStyle;
 }
-function processStyleVariants(props, variants, results = []) {
+function processStyleVariants(props, variants, results = [], layerName = undefined) {
   let mergedState; // We might not need it, initialized lazily
 
   variantLoop: for (let i = 0; i < variants.length; i += 1) {
@@ -84,9 +91,9 @@ function processStyleVariants(props, variants, results = []) {
         ...props.ownerState,
         ownerState: props.ownerState
       };
-      results.push(variant.style(mergedState));
+      results.push(layerName ? shallowLayer(serializeStyles(variant.style(mergedState)), layerName) : variant.style(mergedState));
     } else {
-      results.push(variant.style);
+      results.push(layerName ? shallowLayer(serializeStyles(variant.style), layerName) : variant.style);
     }
   }
   return results;
@@ -115,6 +122,7 @@ export default function createStyled(input = {}) {
       overridesResolver = defaultOverridesResolver(lowercaseFirstLetter(componentSlot)),
       ...options
     } = inputOptions;
+    const layerName = componentName && componentName.startsWith('Mui') || !!componentSlot ? 'components' : 'custom';
 
     // if skipVariantsResolver option is defined, take the value, otherwise, true for root and false for other slots.
     const skipVariantsResolver = inputSkipVariantsResolver !== undefined ? inputSkipVariantsResolver :
@@ -151,16 +159,16 @@ export default function createStyled(input = {}) {
       }
       if (typeof style === 'function') {
         return function styleFunctionProcessor(props) {
-          return processStyle(props, style);
+          return processStyle(props, style, props.theme.modularCssLayers ? layerName : undefined);
         };
       }
       if (isPlainObject(style)) {
         const serialized = preprocessStyles(style);
-        if (!serialized.variants) {
-          return serialized.style;
-        }
         return function styleObjectProcessor(props) {
-          return processStyle(props, serialized);
+          if (!serialized.variants) {
+            return props.theme.modularCssLayers ? shallowLayer(serialized.style, layerName) : serialized.style;
+          }
+          return processStyle(props, serialized, props.theme.modularCssLayers ? layerName : undefined);
         };
       }
       return style;
@@ -185,7 +193,7 @@ export default function createStyled(input = {}) {
           // TODO: v7 remove iteration and use `resolveStyleArg(styleOverrides[slot])` directly
           // eslint-disable-next-line guard-for-in
           for (const slotKey in styleOverrides) {
-            resolvedStyleOverrides[slotKey] = processStyle(props, styleOverrides[slotKey]);
+            resolvedStyleOverrides[slotKey] = processStyle(props, styleOverrides[slotKey], props.theme.modularCssLayers ? 'theme' : undefined);
           }
           return overridesResolver(props, resolvedStyleOverrides);
         });
@@ -197,7 +205,7 @@ export default function createStyled(input = {}) {
           if (!themeVariants) {
             return null;
           }
-          return processStyleVariants(props, themeVariants);
+          return processStyleVariants(props, themeVariants, [], props.theme.modularCssLayers ? 'theme' : undefined);
         });
       }
       if (!skipSx) {

package/esm/styleFunctionSx/styleFunctionSx.js

@@ -64,7 +64,8 @@ export function unstable_createStyleFunctionSx() {
   function styleFunctionSx(props) {
     const {
       sx,
-      theme = {}
+      theme = {},
+      nested
     } = props || {};
     if (!sx) {
       return null; // Emotion & styled-components will neglect null
@@ -105,7 +106,8 @@ export function unstable_createStyleFunctionSx() {
               if (objectsHaveSameKeys(breakpointsValues, value)) {
                 css[styleKey] = styleFunctionSx({
                   sx: value,
-                  theme
+                  theme,
+                  nested: true
                 });
               } else {
                 css = merge(css, breakpointsValues);
@@ -116,6 +118,11 @@ export function unstable_createStyleFunctionSx() {
           }
         }
       });
+      if (!nested && theme.modularCssLayers) {
+        return {
+          '@layer sx': sortContainerQueries(theme, removeUnusedBreakpoints(breakpointsKeys, css))
+        };
+      }
       return sortContainerQueries(theme, removeUnusedBreakpoints(breakpointsKeys, css));
     }
     return Array.isArray(sx) ? sx.map(traverse) : traverse(sx);

package/esm/version/index.js

@@ -1,6 +1,6 @@
-export const version = "6.4.12";
+export const version = "6.5.0";
 export const major = Number("6");
-export const minor = Number("4");
-export const patch = Number("12");
+export const minor = Number("5");
+export const patch = Number("0");
 export const prerelease = undefined;
 export default version;

package/index.js

@@ -1,5 +1,5 @@
 /**
- * @mui/system v6.4.12
+ * @mui/system v6.5.0
  *
  * @license MIT
  * This source code is licensed under the MIT license found in the

package/modern/GlobalStyles/GlobalStyles.js

@@ -2,16 +2,40 @@
 
 import * as React from 'react';
 import PropTypes from 'prop-types';
-import { GlobalStyles as MuiGlobalStyles } from '@mui/styled-engine';
+import { GlobalStyles as MuiGlobalStyles, internal_serializeStyles as serializeStyles } from '@mui/styled-engine';
 import useTheme from "../useTheme/index.js";
 import { jsx as _jsx } from "react/jsx-runtime";
+function wrapGlobalLayer(styles) {
+  const serialized = serializeStyles(styles);
+  if (styles !== serialized && serialized.styles) {
+    if (!serialized.styles.match(/^@layer\s+[^{]*$/)) {
+      // If the styles are not already wrapped in a layer, wrap them in a global layer.
+      serialized.styles = `@layer global{${serialized.styles}}`;
+    }
+    return serialized;
+  }
+  return styles;
+}
 function GlobalStyles({
   styles,
   themeId,
   defaultTheme = {}
 }) {
   const upperTheme = useTheme(defaultTheme);
-  const globalStyles = typeof styles === 'function' ? styles(themeId ? upperTheme[themeId] || upperTheme : upperTheme) : styles;
+  const resolvedTheme = themeId ? upperTheme[themeId] || upperTheme : upperTheme;
+  let globalStyles = typeof styles === 'function' ? styles(resolvedTheme) : styles;
+  if (resolvedTheme.modularCssLayers) {
+    if (Array.isArray(globalStyles)) {
+      globalStyles = globalStyles.map(styleArg => {
+        if (typeof styleArg === 'function') {
+          return wrapGlobalLayer(styleArg(resolvedTheme));
+        }
+        return wrapGlobalLayer(styleArg);
+      });
+    } else {
+      globalStyles = wrapGlobalLayer(globalStyles);
+    }
+  }
   return /*#__PURE__*/_jsx(MuiGlobalStyles, {
     styles: globalStyles
   });

package/modern/ThemeProvider/ThemeProvider.js

@@ -8,7 +8,8 @@ import { ThemeContext as StyledEngineThemeContext } from '@mui/styled-engine';
 import useThemeWithoutDefault from "../useThemeWithoutDefault/index.js";
 import RtlProvider from "../RtlProvider/index.js";
 import DefaultPropsProvider from "../DefaultPropsProvider/index.js";
-import { jsx as _jsx } from "react/jsx-runtime";
+import useLayerOrder from "./useLayerOrder.js";
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
 const EMPTY_THEME = {};
 function useThemeScoping(themeId, upperTheme, localTheme, isPrivate = false) {
   return React.useMemo(() => {
@@ -59,15 +60,16 @@ function ThemeProvider(props) {
   const engineTheme = useThemeScoping(themeId, upperTheme, localTheme);
   const privateTheme = useThemeScoping(themeId, upperPrivateTheme, localTheme, true);
   const rtlValue = (themeId ? engineTheme[themeId] : engineTheme).direction === 'rtl';
+  const layerOrder = useLayerOrder(engineTheme);
   return /*#__PURE__*/_jsx(MuiThemeProvider, {
     theme: privateTheme,
     children: /*#__PURE__*/_jsx(StyledEngineThemeContext.Provider, {
       value: engineTheme,
       children: /*#__PURE__*/_jsx(RtlProvider, {
         value: rtlValue,
-        children: /*#__PURE__*/_jsx(DefaultPropsProvider, {
+        children: /*#__PURE__*/_jsxs(DefaultPropsProvider, {
           value: themeId ? engineTheme[themeId].components : engineTheme.components,
-          children: children
+          children: [layerOrder, children]
         })
       })
     })

package/modern/ThemeProvider/useLayerOrder.js

@@ -0,0 +1,52 @@
+import * as React from 'react';
+import useEnhancedEffect from '@mui/utils/useEnhancedEffect';
+import useId from '@mui/utils/useId';
+import GlobalStyles from "../GlobalStyles/index.js";
+import useThemeWithoutDefault from "../useThemeWithoutDefault/index.js";
+
+/**
+ * This hook returns a `GlobalStyles` component that sets the CSS layer order (for server-side rendering).
+ * Then on client-side, it injects the CSS layer order into the document head to ensure that the layer order is always present first before other Emotion styles.
+ */
+import { jsx as _jsx } from "react/jsx-runtime";
+export default function useLayerOrder(theme) {
+  const upperTheme = useThemeWithoutDefault();
+  const id = useId() || '';
+  const {
+    modularCssLayers
+  } = theme;
+  let layerOrder = 'mui.global, mui.components, mui.theme, mui.custom, mui.sx';
+  if (!modularCssLayers || upperTheme !== null) {
+    // skip this hook if upper theme exists.
+    layerOrder = '';
+  } else if (typeof modularCssLayers === 'string') {
+    layerOrder = modularCssLayers.replace(/mui(?!\.)/g, layerOrder);
+  } else {
+    layerOrder = `@layer ${layerOrder};`;
+  }
+  useEnhancedEffect(() => {
+    const head = document.querySelector('head');
+    if (!head) {
+      return;
+    }
+    const firstChild = head.firstChild;
+    if (layerOrder) {
+      // Only insert if first child doesn't have data-mui-layer-order attribute
+      if (firstChild && firstChild.hasAttribute?.('data-mui-layer-order') && firstChild.getAttribute('data-mui-layer-order') === id) {
+        return;
+      }
+      const styleElement = document.createElement('style');
+      styleElement.setAttribute('data-mui-layer-order', id);
+      styleElement.textContent = layerOrder;
+      head.prepend(styleElement);
+    } else {
+      head.querySelector(`style[data-mui-layer-order="${id}"]`)?.remove();
+    }
+  }, [layerOrder, id]);
+  if (!layerOrder) {
+    return null;
+  }
+  return /*#__PURE__*/_jsx(GlobalStyles, {
+    styles: layerOrder
+  });
+}

package/modern/createStyled/createStyled.js

@@ -1,4 +1,4 @@
-import styledEngineStyled, { internal_mutateStyles as mutateStyles } from '@mui/styled-engine';
+import styledEngineStyled, { internal_mutateStyles as mutateStyles, internal_serializeStyles as serializeStyles } from '@mui/styled-engine';
 import { isPlainObject } from '@mui/utils/deepmerge';
 import capitalize from '@mui/utils/capitalize';
 import getDisplayName from '@mui/utils/getDisplayName';
@@ -16,6 +16,13 @@ export const systemDefaultTheme = createTheme();
 export function shouldForwardProp(prop) {
   return prop !== 'ownerState' && prop !== 'theme' && prop !== 'sx' && prop !== 'as';
 }
+function shallowLayer(serialized, layerName) {
+  if (layerName && serialized && typeof serialized === 'object' && serialized.styles && !serialized.styles.startsWith('@layer') // only add the layer if it is not already there.
+  ) {
+    serialized.styles = `@layer ${layerName}{${String(serialized.styles)}}`;
+  }
+  return serialized;
+}
 function defaultOverridesResolver(slot) {
   if (!slot) {
     return null;
@@ -25,7 +32,7 @@ function defaultOverridesResolver(slot) {
 function attachTheme(props, themeId, defaultTheme) {
   props.theme = isObjectEmpty(props.theme) ? defaultTheme : props.theme[themeId] || props.theme;
 }
-function processStyle(props, style) {
+function processStyle(props, style, layerName) {
   /*
    * Style types:
    *  - null/undefined
@@ -37,27 +44,27 @@ function processStyle(props, style) {
 
   const resolvedStyle = typeof style === 'function' ? style(props) : style;
   if (Array.isArray(resolvedStyle)) {
-    return resolvedStyle.flatMap(subStyle => processStyle(props, subStyle));
+    return resolvedStyle.flatMap(subStyle => processStyle(props, subStyle, layerName));
   }
   if (Array.isArray(resolvedStyle?.variants)) {
     let rootStyle;
     if (resolvedStyle.isProcessed) {
-      rootStyle = resolvedStyle.style;
+      rootStyle = layerName ? shallowLayer(resolvedStyle.style, layerName) : resolvedStyle.style;
     } else {
       const {
         variants,
         ...otherStyles
       } = resolvedStyle;
-      rootStyle = otherStyles;
+      rootStyle = layerName ? shallowLayer(serializeStyles(otherStyles), layerName) : otherStyles;
     }
-    return processStyleVariants(props, resolvedStyle.variants, [rootStyle]);
+    return processStyleVariants(props, resolvedStyle.variants, [rootStyle], layerName);
   }
   if (resolvedStyle?.isProcessed) {
-    return resolvedStyle.style;
+    return layerName ? shallowLayer(serializeStyles(resolvedStyle.style), layerName) : resolvedStyle.style;
   }
-  return resolvedStyle;
+  return layerName ? shallowLayer(serializeStyles(resolvedStyle), layerName) : resolvedStyle;
 }
-function processStyleVariants(props, variants, results = []) {
+function processStyleVariants(props, variants, results = [], layerName = undefined) {
   let mergedState; // We might not need it, initialized lazily
 
   variantLoop: for (let i = 0; i < variants.length; i += 1) {
@@ -84,9 +91,9 @@ function processStyleVariants(props, variants, results = []) {
         ...props.ownerState,
         ownerState: props.ownerState
       });
-      results.push(variant.style(mergedState));
+      results.push(layerName ? shallowLayer(serializeStyles(variant.style(mergedState)), layerName) : variant.style(mergedState));
     } else {
-      results.push(variant.style);
+      results.push(layerName ? shallowLayer(serializeStyles(variant.style), layerName) : variant.style);
     }
   }
   return results;
@@ -115,6 +122,7 @@ export default function createStyled(input = {}) {
       overridesResolver = defaultOverridesResolver(lowercaseFirstLetter(componentSlot)),
       ...options
     } = inputOptions;
+    const layerName = componentName && componentName.startsWith('Mui') || !!componentSlot ? 'components' : 'custom';
 
     // if skipVariantsResolver option is defined, take the value, otherwise, true for root and false for other slots.
     const skipVariantsResolver = inputSkipVariantsResolver !== undefined ? inputSkipVariantsResolver :
@@ -151,16 +159,16 @@ export default function createStyled(input = {}) {
       }
       if (typeof style === 'function') {
         return function styleFunctionProcessor(props) {
-          return processStyle(props, style);
+          return processStyle(props, style, props.theme.modularCssLayers ? layerName : undefined);
         };
       }
       if (isPlainObject(style)) {
         const serialized = preprocessStyles(style);
-        if (!serialized.variants) {
-          return serialized.style;
-        }
         return function styleObjectProcessor(props) {
-          return processStyle(props, serialized);
+          if (!serialized.variants) {
+            return props.theme.modularCssLayers ? shallowLayer(serialized.style, layerName) : serialized.style;
+          }
+          return processStyle(props, serialized, props.theme.modularCssLayers ? layerName : undefined);
         };
       }
       return style;
@@ -185,7 +193,7 @@ export default function createStyled(input = {}) {
           // TODO: v7 remove iteration and use `resolveStyleArg(styleOverrides[slot])` directly
           // eslint-disable-next-line guard-for-in
           for (const slotKey in styleOverrides) {
-            resolvedStyleOverrides[slotKey] = processStyle(props, styleOverrides[slotKey]);
+            resolvedStyleOverrides[slotKey] = processStyle(props, styleOverrides[slotKey], props.theme.modularCssLayers ? 'theme' : undefined);
           }
           return overridesResolver(props, resolvedStyleOverrides);
         });
@@ -197,7 +205,7 @@ export default function createStyled(input = {}) {
           if (!themeVariants) {
             return null;
           }
-          return processStyleVariants(props, themeVariants);
+          return processStyleVariants(props, themeVariants, [], props.theme.modularCssLayers ? 'theme' : undefined);
         });
       }
       if (!skipSx) {

package/modern/index.js

@@ -1,5 +1,5 @@
 /**
- * @mui/system v6.4.12
+ * @mui/system v6.5.0
  *
  * @license MIT
  * This source code is licensed under the MIT license found in the

package/modern/styleFunctionSx/styleFunctionSx.js

@@ -64,7 +64,8 @@ export function unstable_createStyleFunctionSx() {
   function styleFunctionSx(props) {
     const {
       sx,
-      theme = {}
+      theme = {},
+      nested
     } = props || {};
     if (!sx) {
       return null; // Emotion & styled-components will neglect null
@@ -105,7 +106,8 @@ export function unstable_createStyleFunctionSx() {
               if (objectsHaveSameKeys(breakpointsValues, value)) {
                 css[styleKey] = styleFunctionSx({
                   sx: value,
-                  theme
+                  theme,
+                  nested: true
                 });
               } else {
                 css = merge(css, breakpointsValues);
@@ -116,6 +118,11 @@ export function unstable_createStyleFunctionSx() {
           }
         }
       });
+      if (!nested && theme.modularCssLayers) {
+        return {
+          '@layer sx': sortContainerQueries(theme, removeUnusedBreakpoints(breakpointsKeys, css))
+        };
+      }
       return sortContainerQueries(theme, removeUnusedBreakpoints(breakpointsKeys, css));
     }
     return Array.isArray(sx) ? sx.map(traverse) : traverse(sx);

package/modern/version/index.js

@@ -1,6 +1,6 @@
-export const version = "6.4.12";
+export const version = "6.5.0";
 export const major = Number("6");
-export const minor = Number("4");
-export const patch = Number("12");
+export const minor = Number("5");
+export const patch = Number("0");
 export const prerelease = undefined;
 export default version;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/system",
-  "version": "6.4.12",
+  "version": "6.5.0",
   "private": false,
   "author": "MUI Team",
   "description": "MUI System is a set of CSS utilities to help you build custom designs more efficiently. It makes it possible to rapidly lay out custom designs.",
@@ -30,10 +30,10 @@
     "clsx": "^2.1.1",
     "csstype": "^3.1.3",
     "prop-types": "^15.8.1",
-    "@mui/types": "~7.2.24",
-    "@mui/styled-engine": "^6.4.11",
+    "@mui/styled-engine": "^6.5.0",
     "@mui/private-theming": "^6.4.9",
-    "@mui/utils": "^6.4.9"
+    "@mui/utils": "^6.4.9",
+    "@mui/types": "~7.2.24"
   },
   "peerDependencies": {
     "@emotion/react": "^11.5.0",

package/styleFunctionSx/styleFunctionSx.js

@@ -72,7 +72,8 @@ function unstable_createStyleFunctionSx() {
   function styleFunctionSx(props) {
     const {
       sx,
-      theme = {}
+      theme = {},
+      nested
     } = props || {};
     if (!sx) {
       return null; // Emotion & styled-components will neglect null
@@ -113,7 +114,8 @@ function unstable_createStyleFunctionSx() {
               if (objectsHaveSameKeys(breakpointsValues, value)) {
                 css[styleKey] = styleFunctionSx({
                   sx: value,
-                  theme
+                  theme,
+                  nested: true
                 });
               } else {
                 css = (0, _merge.default)(css, breakpointsValues);
@@ -124,6 +126,11 @@ function unstable_createStyleFunctionSx() {
           }
         }
       });
+      if (!nested && theme.modularCssLayers) {
+        return {
+          '@layer sx': (0, _cssContainerQueries.sortContainerQueries)(theme, (0, _breakpoints.removeUnusedBreakpoints)(breakpointsKeys, css))
+        };
+      }
       return (0, _cssContainerQueries.sortContainerQueries)(theme, (0, _breakpoints.removeUnusedBreakpoints)(breakpointsKeys, css));
     }
     return Array.isArray(sx) ? sx.map(traverse) : traverse(sx);

package/version/index.js

@@ -4,9 +4,9 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.version = exports.prerelease = exports.patch = exports.minor = exports.major = exports.default = void 0;
-const version = exports.version = "6.4.12";
+const version = exports.version = "6.5.0";
 const major = exports.major = Number("6");
-const minor = exports.minor = Number("4");
-const patch = exports.patch = Number("12");
+const minor = exports.minor = Number("5");
+const patch = exports.patch = Number("0");
 const prerelease = exports.prerelease = undefined;
 var _default = exports.default = version;