Text-shadow now configurable via theme.json

WordPress 7.1 introduces the ability to define a text-shadow value in Global Styles through theme.json. Themes can now set a text shadow globally, on specific blocks, and on elements such as links, without a plugin or custom stylesheet.

GitHub issue: #47904 | PR: #73320

This is the first step of the text shadow feature. It covers theme.json styling only. A user interface, presets, and per-block-instance controls arrive in the next release. See the “What is not included yet” section below.

Background

The CSS text-shadow property has been a frequently requested typography feature (see #47904). Until now, applying a text shadow through the block system was not possible. Theme authors had to add their own CSS to style text shadows, which kept the value outside of theme.json and Global Styles.

Fully implementing text shadow raises questions that still need discussion, such as the right control for editing shadows and whether shadows should be stored as presets. To make progress without waiting on those decisions, this release adds the smallest useful piece: the ability to declare a text-shadow value directly in theme.json.

What changed

A textShadow property is now recognized under styles.typography in theme.json. The value maps directly to the CSS text-shadow property, so any valid text-shadow value works, including multiple comma-separated shadows.

The property is supported in the same places as other typography styles:

• Global typography (styles.typography)
• Per-block styles (styles.blocks.<block>.typography)
• Element styles, including states such as :hover (styles.elements.<element>)

There is no block inspector control and no Global Styles interface for this in this release. The value is set in theme.json only.

How to use it

Set textShadow under styles.typography to apply a shadow to all text. The example below applies a global shadow, overrides it for the Paragraph block, and removes the shadow from links on hover.

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 3,
	"styles": {
		"typography": {
			"textShadow": "1px 1px 2px red, 0 0 1em blue, 0 0 0.2em blue"
		},
		"blocks": {
			"core/paragraph": {
				"typography": {
					"textShadow": "1px 1px 2px red, 0 0 1em red, 0 0 0.2em red"
				}
			}
		},
		"elements": {
			"link": {
				":hover": {
					"typography": {
						"textShadow": "none"
					}
				}
			}
		}
	}
}

Block-level values override the global value, following the same cascade as other typography styles.

Editor behavior

When a global text shadow is set, the shadow is removed from the empty rich text placeholder (for example the “Type / to choose a block” prompt). Without this reset, the placeholder text can become hard to read. The reset applies to the placeholder only. Actual content still renders with the configured shadow in both the editor and on the front end.

What is not included yet

This release covers theme.json styling only. The following are planned for the next release in #79584:

• A text shadow control in the block inspector, so a shadow can be set on an individual block instance.
• A Global Styles interface for browsing, creating, and editing text shadow presets.
• Text shadow presets in theme.json (settings.typography.textShadow, textShadowPresets, and defaultTextShadowPresets), each output as a var(--wp--preset--text-shadow--{slug}) custom property.
• A new supports.typography.textShadow block support, enabled first on the Paragraph and Heading blocks.

Until then, text shadow can be configured through theme.json styles as shown above.

Backwards compatibility

These are additive changes. No existing blocks or themes are affected, and no action is required. Themes that do not set textShadow behave exactly as before.

Further Reading

• PR: Global Styles: Add textShadow style support (#73320)
• Tracking issue: Typography: Add “Text shadow” support (#47904)
• Follow-up PR (next release): Add textShadow typography support and UI (#79584)

Props to @wildworks for reviewing this post.

#dev-notes, #dev-notes-7-1