Just like colors and gradients, the shadow block support uses a set of default presets, applied with the help of CSS variables. In the editor, the shadow settings are in the same styles panel as the border settings. The type of shadow used is a box shadow. There are no settings for text shadows.
Theme developers can add new custom shadows with theme.json, and in this short lesson I will show you how.
All code examples in this lesson assume that you are using theme.json version 2 or 3. Remember that you must include the version in your .json file.
Which blocks support shadows?
All blocks can have a default shadow applied in theme.json. The following WordPress core blocks supports the shadow control in the Site Editor and block editor in WordPress version 6.8: Group, button, image, featured image, cover, columns, and column.
Shadow presets
The shadow presets are very similar to the color palette and belong under the theme.json settings section: settings.shadow.
Default shadow presets
WordPress includes a set of shadow presets that it enables by default. Each shadow preset use a custom CSS property, printed in the body. There is no way to customize these shadows in the interface: If you want a shadow with a different size, opacity, color, inset, or on one side of a block, you need to create a custom shadow. The default WordPress shadow presets are:
- Natural: –wp–preset–shadow–natural: 6px 6px 9px rgba(0, 0, 0, 0.2);
- Deep: –wp–preset–shadow–deep: 12px 12px 50px rgba(0, 0, 0, 0.4);
- Sharp: –wp–preset–shadow–sharp: 6px 6px 0px rgba(0, 0, 0, 0.2);
- Outlined: –wp–preset–shadow–outlined: 6px 6px 0px -3px rgba(255, 255, 255, 1), 6px 6px rgba(0, 0, 0, 1);
- Crisp: –wp–preset–shadow–crisp: 6px 6px 0px rgba(0, 0, 0, 1);
Natural
Deep: When using this shadow, I recommend adding margin, or the shadow may be cut off. It depends on what effect you are after.
Sharp
Outlined
Crisp
How to disable the default shadows using theme.json
To disable the default shadow presets, set settings.shadow.defaultPresets to false:
"settings": {
"shadow": {
"defaultPresets": false
}
}How to add custom shadow presets
You can add custom shadows by adding a presets object with the following key and value pairs:
- name: The visible name in the editor.
- slug: The unique identifier, used in the CSS custom property.
- shadow: The CSS value for the box shadow.
All values are strings.
Tip: You can use the CSS variables from your color palette as the color value in the box shadow.
"settings": {
"shadow": {
"presets": [
{
"name": "Shadow 1",
"slug": "shadow-1",
"shadow": "6px 6px 9px rgba(0, 0, 0, 0.2)"
},
{
"name": "Shadow 2",
"slug": "shadow-2",
"shadow": "6px 6px 0px rgba(0, 0, 0, 1)"
}
]
}
}Applying shadow presets and custom shadows
You apply the box shadows under styles.blocks.blockname.shadow in theme.json.
The setting accepts a CSS variable for one of the presets; or a string with a shorthand
box-shadow: offset-x, offset-y, blur-radius, spread-radius, and color.
Using a preset:
"styles": {
"blocks" :{
"core/post-featured-image": {
"shadow": "var(--wp--preset--shadow--natural)"
}
}
}Shorthand example:
"styles": {
"blocks" :{
"core/post-featured-image": {
"shadow": "10px 10px 5px 0px rgba(0,0,0,0.66)"
}
}
}You can add shadows to both blocks and elements:
"styles": {
"elements": {
"button": {
"shadow": "10px 10px 5px 0px rgba(0,0,0,0.66)"
}
}
}And the CSS output for this example is:
.wp-element-button, .wp-block-button__link {
box-shadow: 10px 10px 5px 0px rgb(0 0 0 / 66%);
}Resources
MDN web docs Box shadow reference
MDN web docs Box shadow generator
Shadows in the WordPress design system (Figma)
WordPress.org Theme developer handbook