Background gradients now combine with block images

WordPress 7.1 introduces a new background.gradient block support. It gives blocks a gradient control in the Background panel of the block inspector. Unlike the existing gradient support, it can be combined with a background image so the two render together.

GitHub issue: #32787 | PR: #75859

Background

Until now, the only way to apply a gradient to a block was through the Color panel’s color.gradient support. That value is stored at style.color.gradient and rendered as a background CSS shorthand.

The background shorthand resets every background property, including background-image. This meant a gradient set through color.gradient would conflict with, and override, any background image on the same block. A block could show a gradient or an image, but not both.

What changed

A new background.gradient block support is registered. It stores its value at style.background.gradient, separate from the existing style.color.gradient.

The key difference is that the new support renders through the background-image longhand property instead of the background shorthand. Because it avoids the shorthand, it no longer resets the other background properties. The style engine can then output the gradient and any background image as comma-separated values in a single background-image declaration:

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

The gradient is layered over the image, and both render together.

Key behavior:

• The control appears in the Background panel, next to the existing background image control.
• When background.gradient is enabled for a block, the gradient tab in the Color panel is suppressed to avoid duplicate controls.
• Gradient preset slugs resolve to CSS custom properties, for example var( --wp--preset--gradient--vivid-cyan-blue ).
• When only a gradient is set (no image), it renders on its own as the background-image value.

How to opt in

Add gradient under the background support in block.json:

{
	"supports": {
		"background": {
			"backgroundImage": true,
			"gradient": true,
			"__experimentalDefaultControls": {
				"backgroundImage": true,
				"gradient": true
			}
		}
	}
}

In WordPress 7.1, the Group, Accordion, Pullquote, Post Content, and Quote blocks opt in to the new support.

In theme.json, the gradient can be set through the background styles group, at the root or per block:

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

Block-level values set in the editor override theme defaults, following the same cascade as other block supports.

How it works

Frontend output. Server-side rendering in the background block support reads the gradient value and passes it, together with any background image, to the style engine. The engine merges them into one comma-separated background-image value and injects the result as an inline style on the block wrapper. Serialization for the image and the gradient is checked independently, so a block can skip one while still rendering the other.

Sanitization. Previously, safecss_filter_attr() stripped a background-image value that mixed a gradient function with a url(). In WordPress 7.1, safecss_filter_attr() is updated to allow these combined gradient + url() values, so no additional filter is required.

Relationship to color.gradient

background.gradient is a separate support from color.gradient. Existing blocks that use color.gradient are unchanged and continue to work exactly as before.

This new support also lays the groundwork for eventually migrating gradient handling from color.gradient to background.gradient across blocks, giving a single, more capable background styling system. That migration is not part of this change.

Backwards compatibility

These are additive changes. No existing blocks are broken, and no action is required for most blocks and themes. Blocks that do not opt in to background.gradient behave exactly as they did before, including any current use of color.gradient.

Summary

Item

Value

block.json support key

supports.background.gradient

Style storage path

style.background.gradient

theme.json path

styles.background.gradient (and per block)

Rendered CSS property

background-image (comma-separated with any image)

Core adopters (7.1)

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

Further Reading

• PR #75859: Block Supports: Add background gradient support that can combine with background images
• Issue #32787

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