Implementing Text Shadow Support in WordPress 7.1 Global Styles

Introduction to Text Shadow in WordPress 7.1

Typography control in WordPress core expands significantly with the release of version 7.1, addressing long-standing feature request #47904. Previously, applying CSS text shadows required theme developers to bundle custom stylesheets or rely on third-party plugins, keeping styling rules outside the native Global Styles ecosystem. WordPress 7.1 changes this by introducing direct property support for text-shadow inside theme.json.

Covered under pull request #73320, this initial phase focuses entirely on stylesheet declarations through theme.json. It lays the groundwork for advanced typography rules without waiting for complex UI controls or preset management systems to mature. Theme authors can now define drop shadows, glows, and multi-layered visual effects globally, per block, or scoped to specific element interactive states using standard CSS values.

Understanding the theme.json Architecture for Typography

The implementation maps the new property directly to the underlying CSS text-shadow specification. This means any valid CSS shadow value—including multiple comma-separated values for complex effects—functions immediately. The property sits within the standard typography configuration object, maintaining consistency with existing properties like fontSize, lineHeight, and fontFamily.

By integrating directly into the core cascade, declarations made in theme.json output optimized inline styles or global CSS variables depending on how the editor compiles the active theme. Because this is an additive change, themes omitting the property remain entirely unaffected, preserving backwards compatibility across legacy installations.

Configuring Global Text Shadows

Global application affects all typography across the site unless overridden by specific block rules or element states. To apply a site-wide text shadow, target the root styles.typography object within your theme’s configuration file.

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "styles": {
    "typography": {
      "textShadow": "1px 1px 2px rgba(0, 0, 0, 0.4)"
    }
  }
}

This snippet applies a subtle dark drop shadow to every text node rendered on the front end and inside the editor canvas, except where specific UI constraints or descendant selectors override it.

Applying Shadows to Specific Blocks

Granular control allows developers to isolate shadow rules to individual blocks. Using the styles.blocks path, you can target core blocks like paragraphs, headings, or quotes independently from the global defaults. Block-level declarations override global rules following standard CSS cascade logic.

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "styles": {
    "typography": {
      "textShadow": "1px 1px 2px rgba(0, 0, 0, 0.2)"
    },
    "blocks": {
      "core/paragraph": {
        "typography": {
          "textShadow": "2px 2px 4px rgba(255, 0, 0, 0.5)"
        }
      }
    }
  }
}

In this example, site text receives a subtle neutral shadow, while all core paragraph blocks receive a distinct, heavier reddish shadow.

Targeting Elements and Interactive States

Beyond blocks, theme.json supports element-level scoping, including pseudo-classes like :hover. This enables dynamic typographic feedback without needing custom CSS files compiled via build tools.

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "styles": {
    "elements": {
      "link": {
        ":hover": {
          "typography": {
            "textShadow": "none"
          }
        }
      }
    }
  }
}

By setting the hover state of links to none, you can strip away inherited global shadows when users mouse over hyperlinks, improving readability on interactive elements.

Editor Behavior and Placeholder Mitigation

Applying global text shadows introduces potential usability hurdles inside the block editor, particularly with empty rich text inputs. If a heavy shadow applies indiscriminately, prompts like the default “Type / to choose a block” placeholder become visually cluttered and difficult to parse.

To counteract this, WordPress 7.1 automatically strips the text shadow from empty rich text placeholders in the editor canvas. This reset is isolated strictly to the empty placeholder state; actual content populated by the user renders with the configured theme shadow intact in both the block editor and the front end.

Limitations and What is Omitted in WordPress 7.1

Because this release represents the first phase of the text shadow initiative, several expected features are intentionally excluded and slated for a follow-up release via tracking issue #79584:

• No Block Inspector UI: Individual block instances cannot yet be styled via the sidebar controls.
• No Global Styles Interface: Users cannot browse, create, or modify text shadows visually within the Site Editor.
• No Preset Engine: settings.typography.textShadow and associated custom property generation (such as var(--wp--preset--text-shadow--*)) are not yet available.
• No Block Supports Flag: The supports.typography.textShadow block support attribute is inactive for individual block registration.

Developers must rely entirely on manual theme.json declarations for this release cycle.

Practical Implementation Checklist

When incorporating text shadows into your next theme build, follow these steps to ensure robust performance:

1. Verify your theme uses version: 3 in your theme.json schema.
2. Test complex multi-layered shadows across both light and dark backgrounds to maintain WCAG contrast compliance.
3. Check empty block placeholders in the block editor to confirm the automated style reset prevents visual artifacting.
4. Document your custom shadow values for content editors, noting that UI controls will arrive in a subsequent WordPress release.

Primary reference: Review the original announcement for exact release details. This article is an independent explanation and does not reproduce the source text.