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

Theme shadow

Learn about the default theme's shadow scale and how to customize it.

Default tokens

Joy UI uses a T-shirt scale (sm, md, lg, etc.) for defining shadows used by components such as Card, Menu, and more. These tokens are grouped inside the theme.shadow node:

Copied

Token

Value

Light

Dark

xs

sm

md

lg

xl

Customizing the default shadow

Provide key-values to the shadow node to override the default shadows:

<span class="token keyword">import</span> <span class="token punctuation">{</span> extendTheme <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'@mui/joy/styles'</span><span class="token punctuation">;</span>

<span class="token keyword">const</span> theme <span class="token operator">=</span> <span class="token function">extendTheme</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
  <span class="token literal-property property">shadow</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token literal-property property">xs</span><span class="token operator">:</span> <span class="token string">'{CSS box-shadow}'</span><span class="token punctuation">,</span>
    <span class="token literal-property property">sm</span><span class="token operator">:</span> <span class="token string">'{CSS box-shadow}'</span><span class="token punctuation">,</span>
    <span class="token literal-property property">md</span><span class="token operator">:</span> <span class="token string">'{CSS box-shadow}'</span><span class="token punctuation">,</span>
    <span class="token literal-property property">lg</span><span class="token operator">:</span> <span class="token string">'{CSS box-shadow}'</span><span class="token punctuation">,</span>
    <span class="token literal-property property">xl</span><span class="token operator">:</span> <span class="token string">'{CSS box-shadow}'</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">// Then, pass it to `&lt;CssVarsProvider theme={theme}>`.</span>

Adding new shadows

You can add any custom keys to the shadow node:

<span class="token keyword">import</span> <span class="token punctuation">{</span> extendTheme <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'@mui/joy/styles'</span><span class="token punctuation">;</span>

<span class="token keyword">const</span> theme <span class="token operator">=</span> <span class="token function">extendTheme</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
  <span class="token literal-property property">shadow</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token literal-property property">subtle</span><span class="token operator">:</span> <span class="token string">'{CSS box-shadow}'</span><span class="token punctuation">,</span>
    <span class="token literal-property property">strong</span><span class="token operator">:</span> <span class="token string">'{CSS box-shadow}'</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">// Then, pass it to `&lt;CssVarsProvider theme={theme}>`.</span>

TypeScript

When working in TypeScript, you need to augment the theme's Shadow interface with the new keys:

<span class="token comment">// You can put this to any file that's included in your tsconfig</span>
declare module <span class="token string">'@mui/joy/styles'</span> <span class="token punctuation">{</span>
  <span class="token keyword">interface</span> <span class="token class-name">Shadow</span> <span class="token punctuation">{</span>
    subtle<span class="token operator">:</span> string<span class="token punctuation">;</span>
    strong<span class="token operator">:</span> string<span class="token punctuation">;</span>
  <span class="token punctuation">}</span>
<span class="token punctuation">}</span>

Shadow ring

The shadow ring can be configured for both light and dark color schemes. To create a shadow ring, provide a valid CSS box-shadow value to the shadowRing node:

<span class="token keyword">import</span> <span class="token punctuation">{</span> extendTheme <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'@mui/joy/styles'</span><span class="token punctuation">;</span>

<span class="token keyword">const</span> theme <span class="token operator">=</span> <span class="token function">extendTheme</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
  <span class="token literal-property property">colorSchemes</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token literal-property property">light</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token comment">// This creates a 1px box-shadow.</span>
      <span class="token literal-property property">shadowRing</span><span class="token operator">:</span> <span class="token string">'0 0 0 1px rgba(0 0 0 / 0.1)'</span><span class="token punctuation">,</span>
    <span class="token punctuation">}</span><span class="token punctuation">,</span>
    <span class="token literal-property property">dark</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">shadowChannel</span><span class="token operator">:</span> <span class="token string">'0 0 0 1px rgba(255 255 255 / 0.1)'</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">// Then, pass it to `&lt;CssVarsProvider theme={theme}>`.</span>

Shadow colors

The color of the shadow comes from the theme token named var(--joy-shadowChannel). You can customize the value for both light and dark color schemes:

<span class="token keyword">import</span> <span class="token punctuation">{</span> extendTheme <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'@mui/joy/styles'</span><span class="token punctuation">;</span>

<span class="token keyword">const</span> theme <span class="token operator">=</span> <span class="token function">extendTheme</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
  <span class="token literal-property property">colorSchemes</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token literal-property property">light</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">shadowChannel</span><span class="token operator">:</span> <span class="token string">'12 12 12'</span><span class="token punctuation">,</span>
    <span class="token punctuation">}</span><span class="token punctuation">,</span>
    <span class="token literal-property property">dark</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">shadowChannel</span><span class="token operator">:</span> <span class="token string">'0 0 0'</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">// Then, pass it to `&lt;CssVarsProvider theme={theme}>`.</span>

Customizing shadows on an element

To customize a shadow color or shadow ring on a specific instance, use the raw value from the theme.shadow.*.

<span class="token comment">// ✅</span>
<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Button</span></span>
  <span class="token attr-name">sx</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 parameter">theme</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">(</span><span class="token punctuation">{</span>
    <span class="token literal-property property">boxShadow</span><span class="token operator">:</span> theme<span class="token punctuation">.</span>shadow<span class="token punctuation">.</span>md<span class="token punctuation">,</span>
    <span class="token string-property property">'--joy-shadowChannel'</span><span class="token operator">:</span> theme<span class="token punctuation">.</span>vars<span class="token punctuation">.</span>palette<span class="token punctuation">.</span>primary<span class="token punctuation">.</span>mainChannel<span class="token punctuation">,</span>
    <span class="token string-property property">'--joy-shadowRing'</span><span class="token operator">:</span> <span class="token string">'inset 0 -3px 0 rgba(0 0 0 / 0.24)'</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">}</span></span>
<span class="token punctuation">></span></span>

<span class="token comment">// ❌ Both of these do not work</span>
<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Button</span></span>
  <span class="token attr-name">sx</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 parameter">theme</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">(</span><span class="token punctuation">{</span>
    <span class="token literal-property property">boxShadow</span><span class="token operator">:</span> <span class="token string">'md'</span><span class="token punctuation">,</span>
    <span class="token string-property property">'--joy-shadowChannel'</span><span class="token operator">:</span> theme<span class="token punctuation">.</span>vars<span class="token punctuation">.</span>palette<span class="token punctuation">.</span>primary<span class="token punctuation">.</span>mainChannel<span class="token punctuation">,</span>
    <span class="token string-property property">'--joy-shadowRing'</span><span class="token operator">:</span> <span class="token string">'inset 0 -3px 0 rgba(0 0 0 / 0.24)'</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">)</span><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">Button</span></span>
  <span class="token attr-name">sx</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 parameter">theme</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">(</span><span class="token punctuation">{</span>
    <span class="token literal-property property">boxShadow</span><span class="token operator">:</span> theme<span class="token punctuation">.</span>vars<span class="token punctuation">.</span>shadow<span class="token punctuation">.</span>md<span class="token punctuation">,</span>
    <span class="token string-property property">'--joy-shadowChannel'</span><span class="token operator">:</span> theme<span class="token punctuation">.</span>vars<span class="token punctuation">.</span>palette<span class="token punctuation">.</span>primary<span class="token punctuation">.</span>mainChannel<span class="token punctuation">,</span>
    <span class="token string-property property">'--joy-shadowRing'</span><span class="token operator">:</span> <span class="token string">'inset 0 -3px 0 rgba(0 0 0 / 0.24)'</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">}</span></span>
<span class="token punctuation">></span></span>