Skip to content
🚀 MUI X v6 is out! Discover what's new and get started now!
Edit this page

@mui/styled-engine

Configuring your preferred styling library.

The default style library used for generating CSS styles for Material UI components is Emotion. All of the Material UI components rely on the styled() API to inject CSS into the page. This API is supported by multiple popular styling libraries, which makes it possible to switch between them in Material UI.

How to switch to styled-components

If you already have styled-components installed, it's possible to use it exclusively. There are currently two packages available to choose from:

  • @mui/styled-engine - a thin wrapper around emotion's styled() API, with the addition of few other required utilities, such as the <GlobalStyles /> component, the css and keyframe helpers, etc. This is the default.
  • @mui/styled-engine-sc - a similar wrapper around styled-components.

These two packages implement the same interface, which makes it possible to replace one with the other. By default, @mui/material has @mui/styled-engine as a dependency, but you can configure your bundler to replace it with @mui/styled-engine-sc.

yarn

If you are using yarn, you can configure it using a package resolution:

package.json

<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">{
</span><span class="token prefix unchanged"> </span><span class="token line">  "dependencies": {
</span></span><span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">    "@mui/styled-engine": "latest"
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">    "@mui/styled-engine": "npm:@mui/styled-engine-sc@latest"
</span></span><span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">  },
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">  "resolutions": {
</span><span class="token prefix inserted">+</span><span class="token line">    "@mui/styled-engine": "npm:@mui/styled-engine-sc@latest"
</span><span class="token prefix inserted">+</span><span class="token line">  },
</span></span><span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">}</span></span>

npm

As package resolutions are not available in npm at this moment, you need to update you bundler's config to add this alias. Here is an example of how you can do it, if you use webpack:

webpack.config.js

<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">module.exports = {
</span><span class="token prefix unchanged"> </span><span class="token line">  //...
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">  resolve: {
</span><span class="token prefix inserted">+</span><span class="token line">    alias: {
</span><span class="token prefix inserted">+</span><span class="token line">      '@mui/styled-engine': '@mui/styled-engine-sc'
</span><span class="token prefix inserted">+</span><span class="token line">    },
</span><span class="token prefix inserted">+</span><span class="token line">  },
</span></span><span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">};</span></span>

If you are using TypeScript, you will need to also update the TSConfig.

tsconfig.json

<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">{
</span><span class="token prefix unchanged"> </span><span class="token line">  "compilerOptions": {
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">    "paths": {
</span><span class="token prefix inserted">+</span><span class="token line">      "@mui/styled-engine": ["./node_modules/@mui/styled-engine-sc"]
</span><span class="token prefix inserted">+</span><span class="token line">    }
</span></span><span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">  },
</span><span class="token prefix unchanged"> </span><span class="token line">}</span></span>

Next.js

next.config.js

<span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">const withTM = require('next-transpile-modules')([
</span><span class="token prefix inserted">+</span><span class="token line">  '@mui/material',
</span><span class="token prefix inserted">+</span><span class="token line">  '@mui/system',
</span><span class="token prefix inserted">+</span><span class="token line">  '@mui/icons-material', // If @mui/icons-material is being used
</span><span class="token prefix inserted">+</span><span class="token line">]);
</span></span>
<span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">module.exports = withTM({
</span></span><span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">webpack: (config) => {
</span><span class="token prefix unchanged"> </span><span class="token line">  config.resolve.alias = {
</span><span class="token prefix unchanged"> </span><span class="token line">    ...config.resolve.alias,
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">    '@mui/styled-engine': '@mui/styled-engine-sc',
</span></span><span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">   };
</span><span class="token prefix unchanged"> </span><span class="token line">   return config;
</span><span class="token prefix unchanged"> </span><span class="token line"> }
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">});</span></span>

Ready-to-use examples

If you are using create-react-app, there is a ready-to-use template in the example projects. You can use these styled-component examples as a reference:

This package-swap approach is identical to the replacement of React with Preact. The Preact team has documented a large number of installation configurations. If you are stuck with Material UI + styled-components, don't hesitate to check out how they solve the problem, as you can likely transfer the solution.

Theme scoping

Material UI, starting from v5.12.0, can coexist with other libraries that depend on emotion or styled-components. To do that, render Material UI's ThemeProvider as an inner provider and use the THEME_ID to store the theme.

<span class="token keyword">import</span> <span class="token punctuation">{</span> ThemeProvider<span class="token punctuation">,</span> <span class="token constant">THEME_ID</span><span class="token punctuation">,</span> createTheme <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'@mui/material/styles'</span><span class="token punctuation">;</span>
<span class="token keyword">import</span> <span class="token punctuation">{</span> AnotherThemeProvider <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'another-ui-library'</span><span class="token punctuation">;</span>

<span class="token keyword">const</span> materialTheme <span class="token operator">=</span> <span class="token function">createTheme</span><span class="token punctuation">(</span>…your theme<span class="token punctuation">)</span><span class="token punctuation">;</span>

<span class="token keyword">function</span> <span class="token function">App</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  <span class="token keyword">return</span> <span class="token punctuation">(</span>
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">AnotherThemeProvider</span></span><span class="token punctuation">></span></span>
      <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">ThemeProvider</span></span> <span class="token attr-name">theme</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span> <span class="token punctuation">[</span><span class="token constant">THEME_ID</span><span class="token punctuation">]</span><span class="token operator">:</span> materialTheme <span class="token punctuation">}</span><span class="token punctuation">}</span></span><span class="token punctuation">></span></span>
        …components from another library and Material <span class="token constant">UI</span>
      <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">ThemeProvider</span></span><span class="token punctuation">></span></span>
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">AnotherThemeProvider</span></span><span class="token punctuation">></span></span>
  <span class="token punctuation">)</span>
<span class="token punctuation">}</span>

The theme of Material UI will be separated from the other library, so when you use APIs such as styled, sx prop, and useTheme, you will be able to access Material UI's theme like you normally would.

Minimum version

Theme scoping has been added to Material UI v5.12.0, so be sure you're running at that version or higher.

Using with Theme UI

Render Material UI's theme provider below Theme UI's provider and assign the material theme to the THEME_ID property.

<span class="token keyword">import</span> <span class="token punctuation">{</span> ThemeUIProvider <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'theme-ui'</span><span class="token punctuation">;</span>
<span class="token keyword">import</span> <span class="token punctuation">{</span> createTheme <span class="token keyword">as</span> materialCreateTheme<span class="token punctuation">,</span> <span class="token constant">THEME_ID</span> <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'@mui/material/styles'</span><span class="token punctuation">;</span>

<span class="token keyword">const</span> themeUITheme <span class="token operator">=</span> <span class="token punctuation">{</span>
  <span class="token literal-property property">fonts</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token literal-property property">body</span><span class="token operator">:</span> <span class="token string">'system-ui, sans-serif'</span><span class="token punctuation">,</span>
    <span class="token literal-property property">heading</span><span class="token operator">:</span> <span class="token string">'"Avenir Next", sans-serif'</span><span class="token punctuation">,</span>
    <span class="token literal-property property">monospace</span><span class="token operator">:</span> <span class="token string">'Menlo, monospace'</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
  <span class="token literal-property property">colors</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token literal-property property">text</span><span class="token operator">:</span> <span class="token string">'#000'</span><span class="token punctuation">,</span>
    <span class="token literal-property property">background</span><span class="token operator">:</span> <span class="token string">'#fff'</span><span class="token punctuation">,</span>
    <span class="token literal-property property">primary</span><span class="token operator">:</span> <span class="token string">'#33e'</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">;</span>

<span class="token keyword">const</span> materialTheme <span class="token operator">=</span> <span class="token function">materialCreateTheme</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

<span class="token keyword">function</span> <span class="token function">App</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  <span class="token keyword">return</span> <span class="token punctuation">(</span>
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">ThemeUIProvider</span></span> <span class="token attr-name">theme</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span>themeUITheme<span class="token punctuation">}</span></span><span class="token punctuation">></span></span>
      <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">MaterialThemeProvider</span></span> <span class="token attr-name">theme</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span> <span class="token punctuation">[</span><span class="token constant">THEME_ID</span><span class="token punctuation">]</span><span class="token operator">:</span> materialTheme <span class="token punctuation">}</span><span class="token punctuation">}</span></span><span class="token punctuation">></span></span>
        Theme <span class="token constant">UI</span> components and Material <span class="token constant">UI</span> components
      <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">MaterialThemeProvider</span></span><span class="token punctuation">></span></span>
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">ThemeUIProvider</span></span><span class="token punctuation">></span></span>
  <span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>

Using with Chakra UI

Render Material UI's theme provider below Chakra UI's provider and assign the material theme to the THEME_ID property.

<span class="token keyword">import</span> <span class="token punctuation">{</span> ChakraProvider<span class="token punctuation">,</span> extendTheme <span class="token keyword">as</span> chakraExtendTheme <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'@chakra-ui/react'</span><span class="token punctuation">;</span>
<span class="token keyword">import</span> <span class="token punctuation">{</span>
  ThemeProvider <span class="token keyword">as</span> MaterialThemeProvider<span class="token punctuation">,</span>
  createTheme <span class="token keyword">as</span> muiCreateTheme<span class="token punctuation">,</span>
  <span class="token constant">THEME_ID</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'@mui/material/styles'</span><span class="token punctuation">;</span>

<span class="token keyword">const</span> chakraTheme <span class="token operator">=</span> <span class="token function">chakraExtendTheme</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token keyword">const</span> materialTheme <span class="token operator">=</span> <span class="token function">muiCreateTheme</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

<span class="token keyword">function</span> <span class="token function">App</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  <span class="token keyword">return</span> <span class="token punctuation">(</span>
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">ChakraProvider</span></span> <span class="token attr-name">theme</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span>chakraTheme<span class="token punctuation">}</span></span> <span class="token attr-name">resetCSS</span><span class="token punctuation">></span></span>
      <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">MaterialThemeProvider</span></span> <span class="token attr-name">theme</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span> <span class="token punctuation">[</span><span class="token constant">THEME_ID</span><span class="token punctuation">]</span><span class="token operator">:</span> materialTheme <span class="token punctuation">}</span><span class="token punctuation">}</span></span><span class="token punctuation">></span></span>
        Chakra <span class="token constant">UI</span> components and Material <span class="token constant">UI</span> components
      <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">MaterialThemeProvider</span></span><span class="token punctuation">></span></span>
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">ChakraProvider</span></span><span class="token punctuation">></span></span>
  <span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>