New Block Support in WordPress 7.1: Background Gradient (background.gradient)

WordPress 7.1 introduces a new background.gradient blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. 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.

GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged by the repository owner. https://github.com/ 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 CSSCSS Cascading Style Sheets. shorthand.

The background shorthand resets every background property, including background-image. This meant a gradient set through color.gradient would conflictconflict A conflict occurs when a patch changes code that was modified after the patch was created. These patches are considered stale, and will require a refresh of the changes before it can be applied, or the conflicts will need to be resolved. 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 filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. 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 migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. 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)
CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. 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