How to Add MUI Box Shadow Styling the Right Way

Applying CSS box-shadow is such a common style requirement that the MUI team built 25 different shadow levels into the theme. In this post we’ll explore:

• What imports are needed for box shadow
• The difference in accessing box shadow from the theme object vs the styling system.
• How to use the elevation prop (a shortcut for box shadow)
• How to apply traditional box shadow CSS.

Here are the Paper component (which uses the elevation prop) and the Stack component (which uses the system to access boxShadow via sx prop) with level 12 box shadow applied:

Here’s a YouTube video version of this post, or watch it below:

Box Shadow Imports in MUI

Whenever you investigate a new component or feature in MUI, it’s good to start with the imports. However, box shadow is a bit perplexing: we don’t need an import to use it in MUI v5, but the docs suggest a couple options anyway:

Here’s the listed import in a format that can be copied.

import { shadows } from '@mui/system';

When I console-logged the shadows object, it logged an arrow function that wasn’t very useful.

All of this is not necessary because the new MUI v5 styling system gives direct access to the theme properties through the sx prop. We’ll explore the details of this in the next section, but the implication is that no imports are needed for using shadow. Take a look at my code in the next section to see a working example with no shadow import.

Accessing MUI Box Shadow from the Theme vs the System

The two MUI methods of accessing box shadow are:

• Directly from the theme object
• Through the system, which abstracts the access to the theme object

Here’s an example of accessing box shadow directly through the theme:

import { styled } from "@mui/material/styles";

const BoxShadowDiv = styled('div')(
  ({ theme }) => `
  margin: ${theme.spacing(2)};
  padding: ${theme.spacing(2)};
  border: 1px solid black;
  box-shadow: ${theme.shadows[12]};
`,
);

This method is typical of React, accessing values via a passed prop.

Here’s an example of accessing box shadow through the MUI System:

import Stack from "@mui/material/Stack";

<Stack
  sx={{
    boxShadow: 12,
    margin: 2,
    padding: 2,
    border: "1px solid black",
  }}
/>

I also accessed spacing values for margin and padding. Notice how clean and abstract this method is. This is one of the advantages of using the sx prop over the styled API.

The MUI team recommends using the system method for three reasons:

• It reduces time spent switching contexts
• It reduces effort in naming things
• It reduces the need to enforce consistency

Read more about the system benefits in the MUI docs here.

Customizing Box Shadow in Theme

You can customize any of the default 25 box shadow values on the theme, or even add additional values. The values are found in theme.shadows, which is an array of string values reflecting CSS box-shadow values. I show how to customize the shadow array values in this post.

Elevation vs. Box Shadow in MUI

A few components in MUI so commonly use shadow that they have an elevation prop that allows even faster access to the theme. Paper is an example.

Paper Component: Applying Box Shadow Through Elevation Prop

<Paper
  elevation={12}
  sx={{
    margin: 2,
    padding: 2,
    border: "1px solid black",
  }}
>

The TypeScript typing on elevation is number, and it will accept any numeric value but will not apply box shadow if the value is not a populated index in the theme shadow array.

Caution: Paper elevation doesn’t work with ‘outlined’ variant.

Stack Component: Applying Box Shadow Through SX

I showed the Stack component with sx boxShadow in a previous section. However, it is worth noting that the boxShadow property in the sx object is far more dynamic than the elevation prop.

Notice that there are four types for boxShadow (plus undefined). This reflects the possibility of passing theme access values to boxShadow, plus passing CSS property values which we will explore in the next section.

Box-Shadow CSS in MUI

We can add ‘raw’ CSS shadow values using sx boxShadow:

<Paper
  sx={{
    boxShadow: '0px 7px 8px -4px rgb(0 0 0 / 20%), 0px 12px 17px 2px rgb(0 0 0 / 14%), 0px 5px 22px 4px rgb(0 0 0 / 12%)',
  }}
>

The values above correspond to the default theme.shadows[12] value.

Passing in raw values allows us to customize shadow offset-x, offset-y, blur-radius, spread-radius, and color for the component shadows.

MUI Box Shadow Color

Color is an optional parameter of the CSS box-shadow API. Here’s an example where I’ve passed a color value to box shadow in sx:

<Paper sx={{ boxShadow: "10px 10px 10px hotpink" }}>
  <Typography>Test Elevation</Typography>
</Paper>

The box shadow values in the theme can be customized with color with similar syntax.

Resources and Related Links

Here’s everything you need to know about the MUI v5 styled API.

Here’s everything you need to know about the MUI v5 `sx` prop.

MUI Shadow Docs