react-test/docs/data/joy/customization/theme-shadow/theme-shadow.md

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:

{{"demo": "ShadowThemeViewer.js", "bg": "inline"}}

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}>`.

:::success We recommend using var(--joy-shadowRing) and var(--joy-shadowChannel) for shadow values, similar to the default token value. :::

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}>`.

:::warning Customizing the theme's shadow ring will affect all Joy UI components that consume the theme's shadows.

If you want to create a shadow ring for a specific element, see Customizing shadows on an element. :::

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}>`.

:::warning The shadowChannel value must be rgb channels, for example 187 187 187. :::

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

:::error Don't use shadows from theme.vars or the shorthand syntax { shadow: '{key}' } because the value points to the global CSS variable which does not work with the custom shadowChannel and shadowRing on the instance. :::

// ✅
<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)',
  })}
>

{{"demo": "CustomShadowOnElement.js"}}