Deep Dive: Leveraging the New Background Gradient Block Support in WordPress 7.1

The Evolution of Background Styling in WordPress

For several releases, the WordPress block editor has steadily expanded its design tools, aiming to reduce the reliance on custom CSS for common layout patterns. However, one persistent limitation has frustrated theme developers and site builders alike: the inability to natively combine a background gradient with a background image on a single block. If a user wanted a subtle dark gradient overlay on top of a hero image to ensure text readability, they were forced to write custom CSS, employ complex nested Group blocks, or rely on third-party block plugins.

WordPress 7.1 solves this architectural limitation by introducing a dedicated background.gradient block support. This new feature decouples gradient styling from the traditional text and background color controls, placing it squarely within the Background panel of the block inspector. By modernizing how the style engine compiles and outputs CSS, WordPress now allows gradients and background images to coexist and render together dynamically.

The Core Problem: Why color.gradient Fell Short

To understand why this change is significant, it is necessary to examine how WordPress previously handled gradients. Until WordPress 7.1, the only native way to apply a gradient to a block was through the Color panel, which relied on the color.gradient support. This value was stored in the block’s attributes under style.color.gradient.

When rendering this value to the frontend, the WordPress style engine generated CSS using the shorthand background property:

/* How color.gradient rendered in previous versions */
background: linear-gradient(135deg, #000 0%, #fff 100%);

In CSS, the background shorthand property acts as a reset. Whenever it is declared, it resets all other unspecifed background properties to their default initial values—including background-image, background-position, background-repeat, and background-size.

Consequently, if a block had both a background image (configured via the Background panel) and a gradient (configured via the Color panel), the style engine’s output would conflict. The shorthand gradient declaration would completely override and wipe out the background image. Users were forced to choose between a background image or a gradient, but never both on the same element.

How background.gradient Works Under the Hood

The introduction of background.gradient bypasses this shorthand conflict entirely. This new support stores its data at a separate path within the block’s attributes: style.background.gradient.

Instead of compiling to the background shorthand, the style engine now outputs the gradient using the background-image longhand property. Because CSS allows multiple comma-separated values within the background-image property, the style engine can dynamically merge both the gradient and the background image URL into a single, valid CSS declaration:

/* Combined output in WordPress 7.1 */
background-image: linear-gradient( 135deg, #000 0%, #fff 100% ), url( 'https://example.com/image.jpg' );

In CSS rendering rules, the first background layer specified in a comma-separated list is drawn on top of subsequent layers. By outputting the gradient first and the image URL second, WordPress ensures that the gradient acts as an overlay on top of the background image. This is highly beneficial for design patterns like darkening a bright background image to maintain WCAG-compliant text contrast.

If a block has a gradient applied but no background image, the style engine gracefully adapts, rendering only the gradient within the background-image property:

/* Output when only a gradient is defined */
background-image: linear-gradient( 135deg, #000 0%, #fff 100% );

Enabling Background Gradient Support in Custom Blocks

To take advantage of this new feature in your custom blocks, you must explicitly opt in via the block’s block.json file. The gradient control is nested under the background support object.

Here is a complete, production-ready block.json configuration demonstrating how to register both background images and background gradients, while also setting them as default visible controls in the editor sidebar:

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "name": "custom/hero-banner",
  "title": "Hero Banner",
  "category": "layout",
  "supports": {
    "background": {
      "backgroundImage": true,
      "gradient": true,
      "__experimentalDefaultControls": {
        "backgroundImage": true,
        "gradient": true
      }
    }
  }
}

By setting __experimentalDefaultControls to true for both properties, you ensure that these panels are expanded and visible to the user by default in the Block Inspector, rather than hidden behind the settings ellipsis menu.

In WordPress 7.1, several core blocks have already opted into this new support by default. These include:

• core/group
• core/accordion
• core/pullquote
• core/post-content
• core/quote

Configuring Gradients in theme.json

Theme developers can define default background gradients at both the global level and the individual block level using theme.json. The configuration mirrors the structure used in block.json, nesting the values under the background styles group.

The following theme.json example demonstrates how to set a global fallback background gradient and a block-specific gradient for the Core Group block:

{
  "version": 3,
  "styles": {
    "background": {
      "gradient": "linear-gradient( 135deg, #000000 0%, #ffffff 100% )"
    },
    "blocks": {
      "core/group": {
        "background": {
          "gradient": "var:preset|gradient|vivid-cyan-blue"
        }
      }
    }
  }
}

When referencing theme presets inside theme.json, use the standard var:preset|gradient|{slug} syntax. The style engine will automatically resolve this to the correct CSS custom property, such as var(--wp--preset--gradient--vivid-cyan-blue), when rendering the block on the frontend.

Sanitization and Security Updates in WordPress 7.1

A significant technical hurdle in implementing this feature was WordPress’s strict inline style sanitization. By default, WordPress filters inline styles applied in the editor and frontend using the safecss_filter_attr() function. This security measure prevents malicious users with lower permissions from injecting harmful CSS (such as exploits hidden inside unvalidated properties).

Historically, safecss_filter_attr() was highly restrictive when parsing the background-image property. It was designed to allow either a clean url() function or a standard gradient function (like linear-gradient() or radial-gradient()), but it would actively strip out any inline style that attempted to combine both in a single, comma-separated declaration.

To support the new background.gradient implementation, WordPress 7.1 updates the underlying parser within safecss_filter_attr(). The function now safely recognizes and permits combined gradient functions and url() declarations. Developers do not need to write custom filters or disable style sanitization to make combined backgrounds work; the core platform handles this securely out of the box.

Backward Compatibility and UI Coexistence

Because WordPress is committed to backward compatibility, the introduction of background.gradient is strictly additive. It does not deprecate or break the existing color.gradient support.

If you have existing custom blocks or third-party plugins that rely on supports.color.gradient, they will continue to function exactly as they did before. Their values will remain stored at style.color.gradient and will render using the background shorthand property.

However, to prevent user interface confusion, WordPress has built-in logic to handle blocks that transition to the new system. When a block opts into the new background.gradient support, the block editor automatically suppresses the gradient tab within the Color panel. This prevents duplicate controls from appearing in the UI, ensuring that users only see a single, unified gradient control located in the Background panel alongside the background image settings.

While a complete core migration of all blocks from color.gradient to background.gradient is planned for future releases, the two systems will safely coexist in the interim, allowing developers to upgrade their custom blocks at their own pace.

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