Theme shadow

Learn about the theme's default shadow 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:

Customizing the default shadow

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

import { extendTheme } from '@mui/joy/styles';

const theme = extendTheme({
  shadow: {
    xs: '{CSS box-shadow}',
    sm: '{CSS box-shadow}',
    md: '{CSS box-shadow}',
    lg: '{CSS box-shadow}',
    xl: '{CSS box-shadow}',
  },
});

// Then, pass it to `<CssVarsProvider theme={theme}>`.

Adding new shadows

You can add any custom keys to the shadow node:

import { extendTheme } from '@mui/joy/styles';

const theme = extendTheme({
  shadow: {
    subtle: '{CSS box-shadow}',
    strong: '{CSS box-shadow}',
  },
});

// Then, pass it to `<CssVarsProvider theme={theme}>`.

TypeScript

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

// You can put this to any file that's included in your tsconfig
declare module '@mui/joy/styles' {
  interface Shadow {
    subtle: string;
    strong: string;
  }
}

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:

import { extendTheme } from '@mui/joy/styles';

const theme = extendTheme({
  colorSchemes: {
    light: {
      // This creates a 1px box-shadow.
      shadowRing: '0 0 0 1px rgba(0 0 0 / 0.1)',
    },
    dark: {
      shadowChannel: '0 0 0 1px rgba(255 255 255 / 0.1)',
    },
  },
});

// Then, pass it to `<CssVarsProvider theme={theme}>`.

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:

import { extendTheme } from '@mui/joy/styles';

const theme = extendTheme({
  colorSchemes: {
    light: {
      shadowChannel: '12 12 12',
    },
    dark: {
      shadowChannel: '0 0 0',
    },
  },
});

// Then, pass it to `<CssVarsProvider theme={theme}>`.

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.*.

// ✅
<Button
  sx={(theme) => ({
    boxShadow: theme.shadow.md,
    '--joy-shadowChannel': theme.vars.palette.primary.mainChannel,
    '--joy-shadowRing': 'inset 0 -3px 0 rgba(0 0 0 / 0.24)',
  })}
>

// ❌ Both of these do not work
<Button
  sx={(theme) => ({
    boxShadow: 'md',
    '--joy-shadowChannel': theme.vars.palette.primary.mainChannel,
    '--joy-shadowRing': 'inset 0 -3px 0 rgba(0 0 0 / 0.24)',
  })}
>
<Button
  sx={(theme) => ({
    boxShadow: theme.vars.shadow.md,
    '--joy-shadowChannel': theme.vars.palette.primary.mainChannel,
    '--joy-shadowRing': 'inset 0 -3px 0 rgba(0 0 0 / 0.24)',
  })}
>

Token	Value	Light	Dark
xs
sm
md
lg
xl