[system] Enable configuring the sx prop in the theme

docs/data/material/customization/theme-components/GlobalThemeOverrideSx.js

@@ -1,30 +1,28 @@
 import * as React from 'react';
-import {
-  ThemeProvider,
-  createTheme,
-  experimental_sx as sx,
-} from '@mui/material/styles';
+import { ThemeProvider, createTheme } from '@mui/material/styles';
 import Chip from '@mui/material/Chip';
 import Check from '@mui/icons-material/Check';
 
 const finalTheme = createTheme({
   components: {
     MuiChip: {
       styleOverrides: {
-        root: sx({
-          // https://mui.com/system/getting-started/the-sx-prop/#spacing
-          px: 1,
-          py: 0.25,
-          // https://mui.com/system/borders/#border-radius
-          borderRadius: 1, // 4px as default.
-        }),
+        root: ({ theme }) =>
+          theme.unstable_sx({
+            // https://mui.com/system/getting-started/the-sx-prop/#spacing
+            px: 1,
+            py: 0.25,
+            // https://mui.com/system/borders/#border-radius
+            borderRadius: 1, // 4px as default.
+          }),
         label: {
           padding: 'initial',
         },
-        icon: sx({
-          mr: 0.5,
-          ml: '-2px',
-        }),
+        icon: ({ theme }) =>
+          theme.unstable_sx({
+            mr: 0.5,
+            ml: '-2px',
+          }),
       },
     },
   },

docs/data/material/customization/theme-components/GlobalThemeOverrideSx.tsx

@@ -1,30 +1,28 @@
 import * as React from 'react';
-import {
-  ThemeProvider,
-  createTheme,
-  experimental_sx as sx,
-} from '@mui/material/styles';
+import { ThemeProvider, createTheme } from '@mui/material/styles';
 import Chip from '@mui/material/Chip';
 import Check from '@mui/icons-material/Check';
 
 const finalTheme = createTheme({
   components: {
     MuiChip: {
       styleOverrides: {
-        root: sx({
-          // https://mui.com/system/getting-started/the-sx-prop/#spacing
-          px: 1,
-          py: 0.25,
-          // https://mui.com/system/borders/#border-radius
-          borderRadius: 1, // 4px as default.
-        }),
+        root: ({ theme }) =>
+          theme.unstable_sx({
+            // https://mui.com/system/getting-started/the-sx-prop/#spacing
+            px: 1,
+            py: 0.25,
+            // https://mui.com/system/borders/#border-radius
+            borderRadius: 1, // 4px as default.
+          }),
         label: {
           padding: 'initial',
         },
-        icon: sx({
-          mr: 0.5,
-          ml: '-2px',
-        }),
+        icon: ({ theme }) =>
+          theme.unstable_sx({
+            mr: 0.5,
+            ml: '-2px',
+          }),
       },
     },
   },

docs/data/material/customization/theme-components/theme-components.md

@@ -116,18 +116,20 @@ const finalTheme = createTheme({
   components: {
     MuiChip: {
       styleOverrides: {
-        root: sx({
-          px: 1,
-          py: 0.25,
-          borderRadius: 1,
-        }),
+        root: ({ theme }) =>
+          theme.unstable_sx({
+            px: 1,
+            py: 0.25,
+            borderRadius: 1,
+          }),
         label: {
           padding: 'initial',
         },
-        icon: sx({
-          mr: 0.5,
-          ml: '-2px',
-        }),
+        icon: ({ theme }) =>
+          theme.unstable_sx({
+            mr: 0.5,
+            ml: '-2px',
+          }),
       },
     },
   },

docs/data/system/experimental-api/configure-the-sx-prop/ChangeTheBehaviorSxProp.js

@@ -0,0 +1,31 @@
+import * as React from 'react';
+import { createTheme, ThemeProvider, Box, Stack } from '@mui/system';
+
+// Retain type safety.
+
+const theme = createTheme({
+  unstable_sxConfig: {
+    // You can now use the background key in sx
+    // by providing direct values from the palette
+    borderRadius: {
+      themeKey: 'shape',
+    },
+  },
+  shape: {
+    sm: 4,
+    md: 8,
+    lg: 12,
+  },
+});
+
+export default function ChangeTheBehaviorSxProp() {
+  return (
+    <Stack direction="row" gap={1}>
+      <ThemeProvider theme={theme}>
+        <Box sx={{ borderRadius: 'sm', border: '1px solid black', p: 4 }} />
+        <Box sx={{ borderRadius: 'md', border: '1px solid black', p: 4 }} />
+        <Box sx={{ borderRadius: 'lg', border: '1px solid black', p: 4 }} />
+      </ThemeProvider>
+    </Stack>
+  );
+}

docs/data/system/experimental-api/configure-the-sx-prop/ChangeTheBehaviorSxProp.tsx

@@ -0,0 +1,38 @@
+import * as React from 'react';
+import { createTheme, ThemeProvider, Box, Stack } from '@mui/system';
+
+// Retain type safety.
+declare module '@mui/system' {
+  interface Shape {
+    sm: number;
+    md: number;
+    lg: number;
+  }
+}
+
+const theme = createTheme({
+  unstable_sxConfig: {
+    // You can now use the background key in sx
+    // by providing direct values from the palette
+    borderRadius: {
+      themeKey: 'shape',
+    },
+  },
+  shape: {
+    sm: 4,
+    md: 8,
+    lg: 12,
+  },
+});
+
+export default function ChangeTheBehaviorSxProp() {
+  return (
+    <Stack direction="row" gap={1}>
+      <ThemeProvider theme={theme}>
+        <Box sx={{ borderRadius: 'sm', border: '1px solid black', p: 4 }} />
+        <Box sx={{ borderRadius: 'md', border: '1px solid black', p: 4 }} />
+        <Box sx={{ borderRadius: 'lg', border: '1px solid black', p: 4 }} />
+      </ThemeProvider>
+    </Stack>
+  );
+}

docs/data/system/experimental-api/configure-the-sx-prop/ChangeTheBehaviorSxProp.tsx.preview

@@ -0,0 +1,5 @@
+<ThemeProvider theme={theme}>
+  <Box sx={{ borderRadius: 'sm', border: '1px solid black', p: 4 }} />
+  <Box sx={{ borderRadius: 'md', border: '1px solid black', p: 4 }} />
+  <Box sx={{ borderRadius: 'lg', border: '1px solid black', p: 4 }} />
+</ThemeProvider>

docs/data/system/experimental-api/configure-the-sx-prop/ExtendTheSxProp.js

@@ -0,0 +1,37 @@
+import * as React from 'react';
+import { createTheme, ThemeProvider, Box, handleBreakpoints } from '@mui/system';
+
+const customTheme = createTheme({
+  unstable_sxConfig: {
+    size: {
+      style: (props) => {
+        const { size, theme } = props;
+
+        const styleFromPropValue = (propValueFinal) => {
+          const value = theme.spacing(propValueFinal);
+
+          return {
+            width: value,
+            height: value,
+          };
+        };
+
+        // Adding support for the breakpoints syntax
+        return handleBreakpoints(props, size, styleFromPropValue);
+      },
+    },
+  },
+});
+
+export default function ExtendSxProp() {
+  return (
+    <ThemeProvider theme={customTheme}>
+      <Box
+        sx={{
+          size: 10,
+          border: '1px solid black',
+        }}
+      />
+    </ThemeProvider>
+  );
+}

docs/data/system/experimental-api/configure-the-sx-prop/ExtendTheSxProp.tsx

@@ -0,0 +1,37 @@
+import * as React from 'react';
+import { createTheme, ThemeProvider, Box, handleBreakpoints } from '@mui/system';
+
+const customTheme = createTheme({
+  unstable_sxConfig: {
+    size: {
+      style: (props) => {
+        const { size, theme } = props;
+
+        const styleFromPropValue = (propValueFinal: number) => {
+          const value = theme.spacing(propValueFinal);
+
+          return {
+            width: value,
+            height: value,
+          };
+        };
+
+        // Adding support for the breakpoints syntax
+        return handleBreakpoints(props, size, styleFromPropValue);
+      },
+    },
+  },
+});
+
+export default function ExtendSxProp() {
+  return (
+    <ThemeProvider theme={customTheme}>
+      <Box
+        sx={{
+          size: 10,
+          border: '1px solid black',
+        }}
+      />
+    </ThemeProvider>
+  );
+}

docs/data/system/experimental-api/configure-the-sx-prop/ExtendTheSxProp.tsx.preview

@@ -0,0 +1,8 @@
+<ThemeProvider theme={customTheme}>
+  <Box
+    sx={{
+      size: 10,
+      border: '1px solid black',
+    }}
+  />
+</ThemeProvider>

docs/data/system/experimental-api/configure-the-sx-prop/configure-the-sx-prop.md

@@ -0,0 +1,26 @@
+# Configure the sx prop
+
+<p class="description">Learn about the experimental API for extending or changing the behavior of the sx prop.</p>
+
+## Extend the sx prop
+
+You can add new keys to be processed by the `sx` prop by extending the `unstable_sxConfig` option inside the theme, as shown below:
+
+{{"demo": "ExtendTheSxProp.js" }}
+
+## Override existing behavior
+
+It is also possible to change some of the existing behavior of the `sx` prop.
+For example, in some design systems, the border radiuses need to be restricted to specific values, instead of allowing any number to be used—as is the default with MUI System.
+You can change this behavior by providing a custom config for the `borderRadius` property:
+
+{{"demo": "ChangeTheBehaviorSxProp.js" }}
+
+## API
+
+Each key in the `unstable_sx` config can define the following properties:
+
+- `cssProperty` (_string_ [optional]): Indicates the CSS property, if it is different than the key
+- `themeKey` (_string_ [optional]): The path of the theme mapping
+- `transform` (_(cssValue: unknown, userValue: unknown) => number | string | React.CSSProperties | CSSObject_ [optional]): Lets users define a function that can transform the value before it's returned
+- `style` (_(props: any) => CSSObject_ [optional]): Offers maximum customizability. Note that you need to make sure that the breakpoint values can be processed

docs/data/system/getting-started/usage/usage.md

@@ -157,9 +157,9 @@ It works with both Emotion and styled-components.
   | Benchmark case                    | Code snippet          | Time normalized |
   | :-------------------------------- | :-------------------- | --------------- |
   | a. Render 1,000 primitives        | `<div className="…">` | 100ms           |
-  | b. Render 1,000 components        | `<Div>`               | 120ms           |
-  | c. Render 1,000 styled components | `<StyledDiv>`         | 160ms           |
-  | d. Render 1,000 Box               | `<Box sx={…}>`        | 370ms           |
+  | b. Render 1,000 components        | `<Div>`               | 112ms           |
+  | c. Render 1,000 styled components | `<StyledDiv>`         | 181ms           |
+  | d. Render 1,000 Box               | `<Box sx={…}>`        | 296ms           |
 
 <!-- #default-branch-switch -->
 

docs/data/system/pages.ts

@@ -63,6 +63,17 @@ const pages = [
     icon: 'CodeIcon',
     children: pagesApi,
   },
+  {
+    pathname: '/system/experimental-api',
+    title: 'Experimental APIs',
+    icon: 'ExperimentIcon',
+    children: [
+      {
+        pathname: '/system/experimental-api/configure-the-sx-prop',
+        title: 'Configure the sx prop',
+      },
+    ],
+  },
   {
     pathname: '/system/styles',
     title: 'Styles',

docs/data/system/styled/UsingWithSx.js

@@ -1,10 +1,5 @@
 import * as React from 'react';
-import {
-  styled,
-  createTheme,
-  ThemeProvider,
-  experimental_sx as sx,
-} from '@mui/system';
+import { styled, createTheme, ThemeProvider } from '@mui/system';
 
 const customTheme = createTheme({
   palette: {
@@ -15,8 +10,8 @@ const customTheme = createTheme({
   },
 });
 
-const MyThemeComponent = styled('div')(
-  sx({
+const MyThemeComponent = styled('div')(({ theme }) =>
+  theme.unstable_sx({
     color: 'primary.contrastText',
     backgroundColor: 'primary.main',
     padding: 1,

docs/data/system/styled/UsingWithSx.tsx

@@ -1,10 +1,5 @@
 import * as React from 'react';
-import {
-  styled,
-  createTheme,
-  ThemeProvider,
-  experimental_sx as sx,
-} from '@mui/system';
+import { styled, createTheme, ThemeProvider } from '@mui/system';
 
 const customTheme = createTheme({
   palette: {
@@ -15,8 +10,8 @@ const customTheme = createTheme({
   },
 });
 
-const MyThemeComponent = styled('div')(
-  sx({
+const MyThemeComponent = styled('div')(({ theme }) =>
+  theme.unstable_sx({
     color: 'primary.contrastText',
     backgroundColor: 'primary.main',
     padding: 1,