@mui/system 7.1.0 → 7.2.0

package/CHANGELOG.md

@@ -1,5 +1,158 @@
 # [Versions](https://mui.com/versions/)
 
+## 7.2.0
+
+<!-- generated comparing v7.1.1..master -->
+
+_Jun 26, 2025_
+
+A big thanks to the 17 contributors who made this release possible. Here are the highlights ✨:
+
+- ⚡️ Added `modularCssLayers` theme option for splitting styles into multiple CSS layers (#46001) @siriwatknp.
+- 📖 Added example for using Material UI with React Router v7 (#46406) @siriwatknp.
+
+### `@mui/material@7.2.0`
+
+- [Backdrop] Fix handling of `component` prop (#46269) @sai6855
+- [Chip] Explicitly define line-height (#46260) @DiegoAndai
+- [Chip] Fix handling on event handlers (#46263) @sai6855
+- [OutlinedInput][Input] Deprecate composed classes (#46316) @sai6855
+- [Select] Pass MenuProps.slotProps.list alongside MenuListProps (#46274) @scousino
+- [l10] Enable `labelDisplayedRows` translation for Romanian (#46377) @dhu-redwoodtech
+- Skip generating `modularCssLayers` CSS var (#46329) @siriwatknp
+
+### `@mui/system@7.2.0`
+
+- Add `modularCssLayers` theme flag to split styles into multiple CSS layers (#46001) @siriwatknp
+
+### `@mui/styled-engine@7.2.0`
+
+- Do not reuse the emotion cache across SSR requests (#46276) @robbtraister
+
+### `@mui/codemod@7.2.0`
+
+- [Dialog] Add codemod for deprecated props (#46328) @sai6855
+
+### Docs
+
+- Don't forward `hasAiSuggestion` (#46415) @bharatkashyap
+- Add introduction to MCP (#46224) @bharatkashyap
+- Fallback for searchbar during SSR (#46364) @Janpot
+- Update InitColorSchemeScript options to match colorSchemeSelector (#46302) @humble-barnacle001
+- Add `ListItemButton` to make the deprecation clear (#46356) @siriwatknp
+- Remove "Unstyled" section from component docs (#46272) @mapache-salvaje
+- Add Testing section to Rating component doc (#46268) @0210shivam
+- Fix fade modal demo (#46271) @brijeshb42
+- [ai] Add suggestions to edit with MUI Chat (#46309) @bharatkashyap
+- [Dialog] Fix form dialog uses ARIA roles on incompatible elements (#46307) @ZeeshanTamboli
+- [Menu] Fix dark mode styling of grouped header demo (#46317) @sai6855
+- [TextField] Removed type="number" demos (#46314) @KirankumarAmbati
+- [examples] Add `material-ui-react-router-ts` example (#46406) @siriwatknp
+
+### Core
+
+- pnpm docs:sync-team (3641a0b) @oliviertassinari
+- Add cross-env to eslint script (#46358) @ZeeshanTamboli
+- Support merging of className and style from theme (#45975) @sai6855
+- [code-infra] Create bundle size package (#45911) @Janpot
+- [docs-infra] Add a script to generate Material UI `llms.txt` and docs markdown. (#46308) @siriwatknp
+- [docs-infra] Fix stackblitz for js projects (#46220) @Janpot
+- [infra] Add emotion as external for bundle monitor (#46372) @Janpot
+- [infra] Create update PR on every canary publish for internal packages (#46367) @Janpot
+- [infra] Remove deprecated esmExternals (#46365) @Janpot
+- [infra] Support project-specific changelog in build scripts (#46425) @michaldudak
+- [toolpad][website] Remove references to Toolpad (#46311) @prakhargupta1
+
+All contributors of this release in alphabetical order: @0210shivam, @bharatkashyap, @brijeshb42, @dhu-redwoodtech, @DiegoAndai, @humble-barnacle001, @Janpot, @KirankumarAmbati, @mapache-salvaje, @michaldudak, @oliviertassinari, @prakhargupta1, @robbtraister, @sai6855, @scousino, @siriwatknp, @ZeeshanTamboli
+
+## 7.1.2
+
+_Jun 18, 2025_
+
+A big thanks to the 2 contributors who made this release possible.
+
+### `@mui/material@7.1.2`
+
+- [Chip] Fix handling on event handlers (#46263) @sai6855
+
+### Docs
+
+- Fix fade modal demo (#46271) @brijeshb42
+
+All contributors of this release in alphabetical order: @brijeshb42, @sai6855
+
+## 7.1.1
+
+<!-- generated comparing v7.1.0..master -->
+
+_May 30, 2025_
+
+A big thanks to the 15 contributors who made this release possible.
+
+### `@mui/material@7.1.1`
+
+- [Autocomplete] Fix label shrink issue when `renderValue` is used with empty array in multiple mode (#46047) @ZeeshanTamboli
+- [Autocomplete] Prevent `renderValue` from being skipped when value is 0 (#46145) @LakshitAgarwal
+- [Autocomplete] Add note in JSDoc for non-TextField components in `renderInput` (#46141) @khllbnomrn
+- [Chip] Add slots and slotProps (#46098) @sai6855
+- [Menu] Remove depreacted `MenuListProps` from demos (#46144) @sai6855
+- [TablePaginationActions] Export TablePaginationActions as new component (#46149) @sai6855
+- [SnackbarContent] Fix `square` prop not working (#46196) @0210shivam
+- [SnackbarContent] Fix error when theme value is CSS variable (#46198) @0210shivam
+
+### `@mui/codemod@7.1.1`
+
+- Add package name option (#45977) @siriwatknp
+
+### `@mui/system@7.1.1`
+
+- Skip styled component from being transformed (#46129) @siriwatknp
+- Update the type for borderRadius (#46154) @codiini
+
+### `@mui/styled-engine@7.1.1`
+
+- Fix variant props callback type to spread `ownerState` (#46187) @siriwatknp
+
+### `@mui/stylis-plugin-rtl@7.1.1`
+
+- Fix RTL does not work with CSS layer with a new package (#46230) @siriwatknp
+
+### Docs
+
+- [Dialog] Remove deprecated TransitionComponent from demo (#46185) @sai6855
+- [Grid] Remove direction `column` and `column-reverse` from the demo (#46127) @0210shivam
+- [Grid] Update grid migration guide (#46057) @sai6855
+- [templates] Fix rendering of logos in dark mode (#46221) @sai6855
+- [ToggleButtonGroup] Add spacing demo (#46058) @sai6855
+- Fix typo in dark mode docs (#46229) @ZeeshanTamboli
+- Clarify Next.js + Tailwind CSS v3 integration requirements (#46176) @chaitanyasharma1011
+- Fix GridLegacy docs order (#46135) @oliviertassinari
+- Update upgrade guide for resolution of `react-is` (#46002) @siriwatknp
+- Remove oudated scaffoldhub ad (#46090) @oliviertassinari
+- Show how to target global state classes with CSS Modules (#45992) @RubemMazzetto
+
+### Core
+
+- [code-infra] Add plugin to check for index file access (#46178) @Janpot
+- [code-infra] Bump eslint to v9 (#46222) @brijeshb42
+- [code-infra] Move packages to mui/mui-public (#46155) @Janpot
+- [code-infra] Move `chai` to peerDep (#46227) @JCQuintas
+- [code-infra] Avoid loading barrel file during type checking (#46177) @Janpot
+- [code-infra] Remove unnecessary ref from `HighlightedCode` component (#46151) @ZeeshanTamboli
+- [code-infra] Import mocha type instead of global (#46108) @JCQuintas
+- [code-infra] Dependabot also create branches (795a481) @oliviertassinari
+- [code-infra] Avoid running continuous release on forks (#46103) @Janpot
+- [code-infra] Remove checkout job altogether (#46100) @Janpot
+- [code-infra] Remove required checkout workflows in circleci (#46099) @Janpot
+- Run pnpm docs:sync-team (c8f1da5) @oliviertassinari
+- Upgrade MUI X packages to v8 (#45990) @KenanYusuf
+- Minor detail to reduce confusion (4c64b72) @oliviertassinari
+- Update security.md (#45839) @DiegoAndai
+- Apply yml convention, blank line only at top level (f273220) @oliviertassinari
+- Add comment that lab should be in alpha (#45999) @oliviertassinari
+
+All contributors of this release in alphabetical order: @0210shivam, @brijeshb42, @chaitanyasharma1011, @codiini, @DiegoAndai, @Janpot, @JCQuintas, @KenanYusuf, @khllbnomrn, @LakshitAgarwal, @oliviertassinari, @RubemMazzetto, @sai6855, @siriwatknp, @ZeeshanTamboli
+
 ## 7.1.0
 
 <!-- generated comparing v7.0.2..master -->

package/DefaultPropsProvider/DefaultPropsProvider.js

@@ -48,11 +48,11 @@ function getThemeProps(params) {
   const config = theme.components[name];
   if (config.defaultProps) {
     // compatible with v5 signature
-    return (0, _resolveProps.default)(config.defaultProps, props);
+    return (0, _resolveProps.default)(config.defaultProps, props, theme.components.mergeClassNameAndStyle);
   }
   if (!config.styleOverrides && !config.variants) {
     // v6 signature, no property 'defaultProps'
-    return (0, _resolveProps.default)(config, props);
+    return (0, _resolveProps.default)(config, props, theme.components.mergeClassNameAndStyle);
   }
   return props;
 }

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 :
@@ -150,21 +158,26 @@ function createStyled(input = {}) {
       ...options
     });
     const transformStyle = style => {
-      // On the server Emotion doesn't use React.forwardRef for creating components, so the created
-      // component stays as a function. This condition makes sure that we do not interpolate functions
-      // which are basically components used as a selectors.
-      if (typeof style === 'function' && style.__emotion_real !== style) {
+      // - On the server Emotion doesn't use React.forwardRef for creating components, so the created
+      //   component stays as a function. This condition makes sure that we do not interpolate functions
+      //   which are basically components used as a selectors.
+      // - `style` could be a styled component from a babel plugin for component selectors, This condition
+      //   makes sure that we do not interpolate them.
+      if (style.__emotion_real === style) {
+        return style;
+      }
+      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;
@@ -189,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);
         });
@@ -201,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/createTheme/shape.d.ts

@@ -1,5 +1,5 @@
 export interface Shape {
-  borderRadius: number;
+  borderRadius: number | string;
 }
 export type ShapeOptions = Partial<Shape>;
 declare const shape: Shape;

package/esm/DefaultPropsProvider/DefaultPropsProvider.js

@@ -40,11 +40,11 @@ function getThemeProps(params) {
   const config = theme.components[name];
   if (config.defaultProps) {
     // compatible with v5 signature
-    return resolveProps(config.defaultProps, props);
+    return resolveProps(config.defaultProps, props, theme.components.mergeClassNameAndStyle);
   }
   if (!config.styleOverrides && !config.variants) {
     // v6 signature, no property 'defaultProps'
-    return resolveProps(config, props);
+    return resolveProps(config, props, theme.components.mergeClassNameAndStyle);
   }
   return props;
 }

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.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/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 :
@@ -141,21 +149,26 @@ export default function createStyled(input = {}) {
       ...options
     });
     const transformStyle = style => {
-      // On the server Emotion doesn't use React.forwardRef for creating components, so the created
-      // component stays as a function. This condition makes sure that we do not interpolate functions
-      // which are basically components used as a selectors.
-      if (typeof style === 'function' && style.__emotion_real !== style) {
+      // - On the server Emotion doesn't use React.forwardRef for creating components, so the created
+      //   component stays as a function. This condition makes sure that we do not interpolate functions
+      //   which are basically components used as a selectors.
+      // - `style` could be a styled component from a babel plugin for component selectors, This condition
+      //   makes sure that we do not interpolate them.
+      if (style.__emotion_real === style) {
+        return style;
+      }
+      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;
@@ -180,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);
         });
@@ -192,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/createTheme/shape.d.ts

@@ -1,5 +1,5 @@
 export interface Shape {
-  borderRadius: number;
+  borderRadius: number | string;
 }
 export type ShapeOptions = Partial<Shape>;
 declare const shape: Shape;

package/esm/index.js

@@ -1,5 +1,5 @@
 /**
- * @mui/system v7.1.0
+ * @mui/system v7.2.0
  *
  * @license MIT
  * This source code is licensed under the MIT license found in the

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 = "7.1.0";
+export const version = "7.2.0";
 export const major = Number("7");
-export const minor = Number("1");
+export const minor = Number("2");
 export const patch = Number("0");
 export const prerelease = undefined;
 export default version;

package/index.js

@@ -1,5 +1,5 @@
 /**
- * @mui/system v7.1.0
+ * @mui/system v7.2.0
  *
  * @license MIT
  * This source code is licensed under the MIT license found in the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/system",
-  "version": "7.1.0",
+  "version": "7.2.0",
   "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.",
   "main": "./index.js",
@@ -25,14 +25,14 @@
     "url": "https://opencollective.com/mui-org"
   },
   "dependencies": {
-    "@babel/runtime": "^7.27.1",
+    "@babel/runtime": "^7.27.6",
     "clsx": "^2.1.1",
     "csstype": "^3.1.3",
     "prop-types": "^15.8.1",
-    "@mui/types": "^7.4.2",
-    "@mui/private-theming": "^7.1.0",
-    "@mui/utils": "^7.1.0",
-    "@mui/styled-engine": "^7.1.0"
+    "@mui/private-theming": "^7.2.0",
+    "@mui/types": "^7.4.4",
+    "@mui/utils": "^7.2.0",
+    "@mui/styled-engine": "^7.2.0"
   },
   "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 = "7.1.0";
+const version = exports.version = "7.2.0";
 const major = exports.major = Number("7");
-const minor = exports.minor = Number("1");
+const minor = exports.minor = Number("2");
 const patch = exports.patch = Number("0");
 const prerelease = exports.prerelease = undefined;
 var _default = exports.default = version;