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

Shadow DOM

The shadow DOM lets you encapsulate parts of an app to keep them separate from global styles that target the regular DOM tree.

How to use the shadow DOM with Material UI

1. Styles

The shadow DOM is an API that provides a way to attach a hidden separated DOM to an element. This is useful when you need to keep the structure, style, and behavior of different components separate from the rest of the code on the page, to prevent conflicts. See the MDN docs on the shadow DOM for more information. The following code snippet shows how to apply styles inside of the shadow DOM:

<span class="token keyword">const</span> container <span class="token operator">=</span> document<span class="token punctuation">.</span><span class="token function">querySelector</span><span class="token punctuation">(</span><span class="token string">'#root'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token keyword">const</span> shadowContainer <span class="token operator">=</span> container<span class="token punctuation">.</span><span class="token function">attachShadow</span><span class="token punctuation">(</span><span class="token punctuation">{</span> mode<span class="token operator">:</span> <span class="token string">'open'</span> <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token keyword">const</span> emotionRoot <span class="token operator">=</span> document<span class="token punctuation">.</span><span class="token function">createElement</span><span class="token punctuation">(</span><span class="token string">'style'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token keyword">const</span> shadowRootElement <span class="token operator">=</span> document<span class="token punctuation">.</span><span class="token function">createElement</span><span class="token punctuation">(</span><span class="token string">'div'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
shadowContainer<span class="token punctuation">.</span><span class="token function">appendChild</span><span class="token punctuation">(</span>emotionRoot<span class="token punctuation">)</span><span class="token punctuation">;</span>
shadowContainer<span class="token punctuation">.</span><span class="token function">appendChild</span><span class="token punctuation">(</span>shadowRootElement<span class="token punctuation">)</span><span class="token punctuation">;</span>

<span class="token keyword">const</span> cache <span class="token operator">=</span> <span class="token function">createCache</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
  key<span class="token operator">:</span> <span class="token string">'css'</span><span class="token punctuation">,</span>
  prepend<span class="token operator">:</span> <span class="token boolean">true</span><span class="token punctuation">,</span>
  container<span class="token operator">:</span> emotionRoot<span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

ReactDOM<span class="token punctuation">.</span><span class="token function">createRoot</span><span class="token punctuation">(</span>shadowRootElement<span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">render</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">CacheProvider</span></span> <span class="token attr-name">value</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span>cache<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">App</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">CacheProvider</span></span><span class="token punctuation">></span></span><span class="token punctuation">,</span>
<span class="token punctuation">)</span><span class="token punctuation">;</span>

2. Theme

Material UI components like Menu, Dialog, Popover and others use Portal to render a new "subtree" in a container outside of current DOM hierarchy. By default, this container is document.body. But since the styles are applied only inside of the Shadow DOM, we need to render portals inside the Shadow DOM container as well:

<span class="token keyword">const</span> theme <span class="token operator">=</span> <span class="token function">createTheme</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
  components<span class="token operator">:</span> <span class="token punctuation">{</span>
    MuiPopover<span class="token operator">:</span> <span class="token punctuation">{</span>
      defaultProps<span class="token operator">:</span> <span class="token punctuation">{</span>
        container<span class="token operator">:</span> shadowRootElement<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>
    MuiPopper<span class="token operator">:</span> <span class="token punctuation">{</span>
      defaultProps<span class="token operator">:</span> <span class="token punctuation">{</span>
        container<span class="token operator">:</span> shadowRootElement<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>
    MuiModal<span class="token operator">:</span> <span class="token punctuation">{</span>
      defaultProps<span class="token operator">:</span> <span class="token punctuation">{</span>
        container<span class="token operator">:</span> shadowRootElement<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 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 comment">// ...</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>theme<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">App</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 punctuation">></span></span><span class="token punctuation">;</span>

Demo

In the example below you can see that the component outside of the shadow DOM is affected by global styles, while the component inside of the shadow DOM is not: