Configure the sx prop

Learn about the experimental API for extending or changing the behavior of the sx prop.

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:

<ThemeProvider theme={customTheme}>
  <Box
    sx={{
      size: 10,
      border: 1,
    }}
  />
</ThemeProvider>

<ThemeProvider theme={customTheme}>
  <Box
    sx={{
      size: 10,
      border: 1,
    }}
  />
</ThemeProvider>

Press Enter to start editing

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:

<ThemeProvider theme={theme}>
  <Box sx={{ borderRadius: 'sm', border: 1, p: 4 }} />
  <Box sx={{ borderRadius: 'md', border: 1, p: 4 }} />
  <Box sx={{ borderRadius: 'lg', border: 1, p: 4 }} />
</ThemeProvider>

<ThemeProvider theme={theme}>
  <Box sx={{ borderRadius: 'sm', border: 1, p: 4 }} />
  <Box sx={{ borderRadius: 'md', border: 1, p: 4 }} />
  <Box sx={{ borderRadius: 'lg', border: 1, p: 4 }} />
</ThemeProvider>

Press Enter to start editing

API

Each value of the config inside unstable_sxConfig accepts 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