Editor: Add a background clip block support to facilitate text gradients by aaronrobertshaw · Pull Request #13491 · WordPress/wordpress-develop

aaronrobertshaw · 2026-09-11T09:41:58Z

Backport of Gutenberg PRs WordPress/gutenberg#77141 and WordPress/gutenberg#77142

Trac ticket: https://core.trac.wordpress.org/ticket/66094

Adds a background.backgroundClip block support. A block can paint its background into border-box, padding-box, content-box, or the text itself, which gives a gradient text fill.

This PR backports:

the backgroundClip definition and value parser in WP_Style_Engine, with a VALID_BACKGROUND_CLIP_VALUES constant,
the setting, style and CSS property mapping in WP_Theme_JSON, with the vendor prefixed declarations,
background-clip and its vendor prefixed companions in the KSES allowlist,
no has-background class when the background is clipped to the text,
the escapes a breakpoint or pseudo state needs over an inherited text clip, in WP_Theme_JSON and the block states support,
the matching tests.

Box values only reset the fill color. Resetting -webkit-background-clip would discard the clip in Chromium.

Without the escapes, a state over a text clip keeps the gradient in its letters.

The editor controls and the Heading and Paragraph opt-ins arrive with the next Gutenberg package update. Until then, the Paragraph breakpoint tests keep their current expectations, and a test block covers the text fill reset.

Testing instructions

Add this to a block theme's theme.json:

"styles": {
	"blocks": {
		"core/heading": {
			"background": {
				"gradient": "linear-gradient(to right,#ff0000,#0000ff)",
				"backgroundClip": "text"
			},
			"@mobile": {
				"color": {
					"text": "#00aa00"
				}
			}
		},
		"core/group": {
			"background": {
				"gradient": "linear-gradient(to right,#ff0000,#0000ff)",
				"backgroundClip": "content-box"
			}
		}
	}
}

Load a page with a Heading and a Group. The global styles should contain:

:root :where(.wp-block-heading){background-image: linear-gradient(to right,#ff0000,#0000ff);background-clip: text;-webkit-background-clip: text;-webkit-text-fill-color: transparent;}
@media (width <= 480px){:root :where(.wp-block-heading){color: #00aa00;-webkit-text-fill-color: currentColor;}}
:root :where(.wp-block-group){background-image: linear-gradient(to right,#ff0000,#0000ff);background-clip: content-box;-webkit-text-fill-color: currentColor;}

The heading shows the gradient on its letters, and plain green at 480px or narrower.
Give the group padding and a thick dashed border. Its gradient stops at the inner edge of the padding.

Use of AI

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5
Used for: the mechanical port

github-actions · 2026-09-11T09:44:59Z

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

All changes will be lost when closing a tab with a Playground instance.
All changes will be lost when refreshing the page.
A fresh instance is created each time the link below is clicked.
Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

github-actions · 2026-09-18T02:33:49Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props aaronrobertshaw, isabel_brison, andrewserong, peterwilsoncc, westonruter.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

aaronrobertshaw · 2026-09-20T08:19:54Z

FYI, things are evolving on the Gutenberg PR this backports. I'll mark this as in draft until that stabilizes.

peterwilsoncc · 2026-10-06T04:09:25Z

@aaronrobertshaw Is this ready for review now that WordPress/gutenberg#77141 has merged?

aaronrobertshaw · 2026-10-08T06:42:49Z

@peterwilsoncc not quite, there is a closely related PR that has changes that might be best backported in this single PR: WordPress/gutenberg#77142.

That Gutenberg PR has a few more changes in the works that might need backporting too. So I'll update as I can and flag this ready once it has the full set of updates.

aaronrobertshaw · 2026-10-14T01:42:29Z

Both WordPress/gutenberg#77141 and WordPress/gutenberg#77142 have now landed in Gutenberg.

This backport has been updated to cover the latest from both PRs and should be ready for an initial review.

tellthemachines

Other than the style engine class changes this LGTM as it's accurate in comparison with the two source PRs.

Not sure about the warnings on the theme.json class though (might be more helpful if these warnings were consistent between the two repos 😅)

peterwilsoncc · 2026-10-14T22:21:35Z

Not sure about the warnings on the theme.json class though (might be more helpful if these warnings were consistent between the two repos 😅)

Either changing the visibility of the methods to protected or replacing static:: with self:: will work, the phpstan issue because the calls will fail if someone extends WP_Theme_JSON. (Props @westonruter for allowing me to lazyweb this one.)

aaronrobertshaw · 2026-10-19T07:09:11Z

Sorry for the delay on this one. I have addressed the feedback and believe this should be good for another review 🙏

Adds a background.backgroundClip block support, so a block can set which box its background is painted into: border-box, padding-box, content-box, or the text itself. Clipping to the text is what gives blocks a gradient text fill. Registers the property in the style engine and theme.json, allows the declarations through KSES, and skips the has-background class when the background is clipped to the text. Props aaronrobertshaw. See #66094.

Backports the PHP from Gutenberg PR 77142. A breakpoint or pseudo state layered over a text clip now unsets the inherited gradient when it sets a box clip, and restores the text fill when it only sets a text color. See #66094.

…radient Backports the PHP from Gutenberg PR 77142. A breakpoint or hover text color on a block that supports the background clip now fills the letters again even when the text gradient comes from global styles. See #66094.

Backports the PHP from Gutenberg PR 77142. A background color on a block that clips its background to the text is clipped to the letters too, so it no longer adds has-background and the padding that comes with it. See #66094.

…lter_attr(). The 7.2.0 line for background-clip sat between the 7.1.0 line and its continuation, so the 7.1.0 transform and clip-path notes read as 7.2.0 changes. It now continues the existing 7.2.0 entry. See #66094.

…elpers.

…orts and theme.json.

Copilot

🟡 Changes recommended

State handling misses applicable clip styles and feature selectors, while invalid clip values can make text invisible.

5 open issues

What changed in this PR

Backports background clipping support into WordPress’s server-side styling pipeline, enabling text gradients and box clipping.

Changes:

Adds clip parsing, theme.json mappings, and allowed CSS properties.
Adjusts background classes and state-specific text-fill resets.
Adds rendering and stylesheet regression tests.

File	Description
tests/phpunit/tests/theme/wpThemeJson.php	Tests responsive and pseudo-state clip handling.
tests/phpunit/tests/style-engine/styleEngine.php	Tests clip declarations and invalid values.
tests/phpunit/tests/block-supports/wpRenderBackgroundSupport.php	Tests clipping output and background classes.
tests/phpunit/tests/block-supports/states.php	Tests state escapes and fill resets.
tests/phpunit/tests/block-supports/colors.php	Tests background classes with clipping.
src/wp-includes/style-engine/class-wp-style-engine.php	Adds clip validation and CSS generation.
src/wp-includes/kses.php	Allows clipping and text-fill properties.
src/wp-includes/class-wp-theme-json.php	Generates clip styles and state escapes.
src/wp-includes/block-supports/states.php	Adds state layering and reset helpers.
src/wp-includes/block-supports/colors.php	Suppresses background classes for clipped colors.
src/wp-includes/block-supports/background.php	Renders clipping and adjusts background classes.

_{Review effort: Balanced}

aaronrobertshaw · 2026-10-19T10:15:30Z

+		$base_clip    = $base_style['background']['backgroundClip'] ?? '';
+		$declarations = array_merge(
+			$declarations,
+			wp_get_state_text_clip_escape( $style, is_string( $base_clip ) ? $base_clip : '' ),


This is rare and the editor matches it today, so I'll address it in a follow-up.

aaronrobertshaw · 2026-10-19T10:15:59Z

+					wp_merge_state_style_objects(
+						$default_root_style,
+						$root_state_style
+					)


This is another rare combination, so I'll fix it in a follow-up with a test.

aaronrobertshaw · 2026-10-19T10:16:19Z

+			unset( $base_path[ $index ] );
+			$layer = _wp_array_get( $tree, array_values( $base_path ) );


Same gap as the block instance case. I'll fix both in the same follow-up.

aaronrobertshaw · 2026-10-19T10:16:35Z

 			 * so those properties are not output twice.
 			 */
 			$declarations = static::compute_style_properties( $node, $settings, null, $this->theme_json, $selector, $use_root_padding );
+			$declarations = self::get_state_declarations_with_text_clip_escapes( $declarations, $node, $base_styles );


No core block can hit this today: only Heading and Paragraph support background clip, and neither uses a color feature selector. I'll include it in the follow-ups.

…lpers.

aaronrobertshaw requested review from andrewserong, ramonjd, talldan and tellthemachines September 11, 2026 09:41

aaronrobertshaw self-assigned this Sep 11, 2026

aaronrobertshaw added the enhancement label Sep 11, 2026

aaronrobertshaw mentioned this pull request Sep 11, 2026

Block Supports and design tools follow-up WordPress/gutenberg#76525

Open

28 of 77 tasks

aaronrobertshaw force-pushed the backport/77141-background-clip-support branch from 582fe2b to 71ac410 Compare September 18, 2026 02:33

aaronrobertshaw marked this pull request as draft September 20, 2026 08:19

github-actions Bot mentioned this pull request Sep 29, 2026

PHP backports for WP 7.2 WordPress/gutenberg#83761

Open

aaronrobertshaw force-pushed the backport/77141-background-clip-support branch from 71ac410 to 1295d58 Compare October 1, 2026 07:45

aaronrobertshaw force-pushed the backport/77141-background-clip-support branch from 1295d58 to 6d8ee2a Compare October 8, 2026 07:30

aaronrobertshaw mentioned this pull request Oct 8, 2026

Block Supports: Add PHP helpers for block support classes and styles #14094

Draft

aaronrobertshaw force-pushed the backport/77141-background-clip-support branch from 6d8ee2a to 4ec37c1 Compare October 12, 2026 04:45

aaronrobertshaw mentioned this pull request Oct 12, 2026

Block Supports: Add background-clip block support UI WordPress/gutenberg#77142

Merged

aaronrobertshaw force-pushed the backport/77141-background-clip-support branch from 8ed54ed to f0dbb85 Compare October 14, 2026 01:40

aaronrobertshaw marked this pull request as ready for review October 14, 2026 01:41

tellthemachines reviewed Oct 14, 2026

View reviewed changes

Comment thread src/wp-includes/style-engine/class-wp-style-engine.php

peterwilsoncc reviewed Oct 14, 2026

View reviewed changes

Comment thread src/wp-includes/class-wp-theme-json.php Outdated

westonruter reviewed Oct 15, 2026

View reviewed changes

Comment thread src/wp-includes/class-wp-theme-json.php Outdated

aaronrobertshaw mentioned this pull request Oct 19, 2026

Block Supports: Share the state text clip helpers with theme.json WordPress/gutenberg#85057

Open

aaronrobertshaw added 7 commits October 19, 2026 15:10

Background clip: Add array shapes and type hints to state text clip h…

1cd84e4

…elpers.

Background clip: Share the state text clip helpers between block supp…

21ffc27

…orts and theme.json.

Docs: Trim the PHPStan shapes on the state text clip helpers.

210bd28

aaronrobertshaw force-pushed the backport/77141-background-clip-support branch from f095d62 to 210bd28 Compare October 19, 2026 07:13

aaronrobertshaw requested a balanced review from Copilot October 19, 2026 07:35

Copilot started reviewing on behalf of aaronrobertshaw October 19, 2026 07:35

View session

Copilot AI reviewed Oct 19, 2026

View reviewed changes

Background clip: Ignore invalid clip values in the state text clip he…

f7a5b04

…lpers.

aaronrobertshaw requested review from peterwilsoncc, tellthemachines and westonruter October 19, 2026 10:16

		unset( $base_path[ $index ] );
		$layer = _wp_array_get( $tree, array_values( $base_path ) );

Conversation

aaronrobertshaw commented Sep 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Testing instructions

Use of AI

Uh oh!

github-actions Bot commented Sep 11, 2026

Test using WordPress Playground

Some things to be aware of

Uh oh!

github-actions Bot commented Sep 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aaronrobertshaw commented Sep 20, 2026

Uh oh!

peterwilsoncc commented Oct 6, 2026

Uh oh!

aaronrobertshaw commented Oct 8, 2026

Uh oh!

aaronrobertshaw commented Oct 14, 2026

Uh oh!

tellthemachines left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

peterwilsoncc commented Oct 14, 2026

Uh oh!

Uh oh!

Uh oh!

aaronrobertshaw commented Oct 19, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

aaronrobertshaw Oct 19, 2026

Choose a reason for hiding this comment

Uh oh!

aaronrobertshaw Oct 19, 2026

Choose a reason for hiding this comment

Uh oh!

aaronrobertshaw Oct 19, 2026

Choose a reason for hiding this comment

Uh oh!

aaronrobertshaw Oct 19, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

aaronrobertshaw commented Sep 11, 2026 •

edited

Loading

github-actions Bot commented Sep 18, 2026 •

edited

Loading