How to add box-shadows with theme.json

Level: ,

Estimated reading time: 2 minutes

Last updated

WordPress 6.1 introduced the first version of the box shadow support. Gutenberg version 15.1 and WordPress version 6.2 adds some improvements, but development is ongoing.

In WordPress 6.1:

  • Support for adding shadows to blocks and elements with theme.json
  • No interface for editing or adding shadows

In WordPress 6.2:

  • Interface for editing shadows for the button block in the Styles Sidebar in the Site Editor.
  • New shadow preset settings.
Shadow presets can be found in the Site Editor under Styles > Blocks> Button > Shadow

Shadow presets

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. The 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);

These can be hidden from the Styles sidebar option by setting shadow.defaultPresets to false:

{
	"version":  2
	settings": {
		"shadow": {
			"defaultPresets": false
		}
	}
}

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.

{
	"version":  2
	settings": {
		"shadow": {
			"presets": [
				{
					"name": "Natural",
					"slug": "natural",
					"shadow": "6px 6px 9px rgba(0, 0, 0, 0.2)"
				},
				{
					"name": "Crisp",
					"slug": "crisp",
					"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%);
}