I've added the "Needs Design Feedback" label as the BackgroundClipControl UI is only an experimental placeholder at the moment:

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.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @jnz31, @CreativeDive, @insaineyesay.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Unlinked contributors: jnz31, CreativeDive, insaineyesay.

Co-authored-by: aaronrobertshaw <aaronrobertshaw@git.wordpress.org>
Co-authored-by: tellthemachines <isabel_brison@git.wordpress.org>
Co-authored-by: ramonjd <ramonopoly@git.wordpress.org>
Co-authored-by: jasmussen <joen@git.wordpress.org>
Co-authored-by: mtias <matveb@git.wordpress.org>
Co-authored-by: luminuu <luminuu@git.wordpress.org>
Co-authored-by: scruffian <scruffian@git.wordpress.org>
Co-authored-by: phil-sola <philsola@git.wordpress.org>
Co-authored-by: andrewserong <andrewserong@git.wordpress.org>
Co-authored-by: justintadlock <greenshady@git.wordpress.org>
Co-authored-by: carolinan <poena@git.wordpress.org>
Co-authored-by: annezazu <annezazu@git.wordpress.org>

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

Size Change: +2.61 kB (+0.04%)

Total Size: 6.87 MB

_{compressed-size-action}

A new BackgroundClipControl component lets users select from the four standard background-clip values — border-box, padding-box, content-box, and text — with live CSS-based previews for each option.

I'm not convinced background-clip is useful as a block support in itself. Reading the issues requesting gradient support for text, I was more thinking this should be an option you could set in text colour. So you'd click color > text, and in the popover you'd have "color" and "gradient" tabs like we currently have in background. Then, if you selected a gradient for text color, background color would either be disabled, or we'd pop up a warning saying that background color doesn't apply to blocks with text color gradients. Does that make sense?

Apart from simplifying the UI, this would have the advantage of not exposing the implementation. Using background-clip to set text gradients is kind of a hack, and it's possible at some point a better way of doing it will be built into CSS, and then we could switch it behind the scenes.

Thanks for getting this PR up. It does what it say on the tin, and opting in only heading and paragraph makes sense to me for now.

I'm also leaning towards the idea that text gradients should live in color. I'm thinking if someone wants gradient text, their minds go to text color, not how a background gets clipped

But background-clip still might still have value as a background property for the other three values.

I'm wondering if there's a way to split concerns. I mean text gradients > color panel, and background clipping to content/padding box > background panel

I don't expect it to be pretty.

Both paths will ultimately want to write to background-clip from two different UI locations, assuming a block supports both. In the case of Group, I guess so. I like the idea of a warning when text gradient is active for example.

I think we'll keep running into inconsistencies with background, e.g., where the controls should live, should they be unified. I'm interested to hear what the design folks say.

Cheers!

Thanks both for the thoughtful feedback 👍

These are exactly the concerns I had in the back of my mind when putting this together, and I should have called them out in the description along with some of the ideas I'd discussed privately (adding a section now).

I agree that a user wanting gradient text will think "text color", not "background clip". That said, I'd push back slightly on calling background-clip a hack. It's the established browser mechanism for this and has been for a long time. Even if CSS for text gradients evolves, I wouldn't expect background clip to go away soon. Especially, as the other methods of background clipping would still have their uses.

One idea I've been turning over, was as touched on already: the block support could adaptively change what control it renders based on which clip values are allowed.

Similar to the enum setting used for the Line Indent block support, we could allow themes to define which background clipping options they wish to expose. Alternatively, we could lean on the default controls to be displayed like the Border control. Displaying only the text option by default would be the equivalent to setting only text via the enum option.

If a theme opts into text only, we could surface a gradient picker directly in the Color panel (text color section) that writes to both background and backgroundClip under the hood. If broader values are enabled (border-box, padding-box, content-box), we fall back to the full clip control in the background panel, or simply display the background clip control in addition, minus the text clipping option.

In other words, I'm aligned with @ramonjd on splitting the concerns: text gradient UX → color panel, clip-to-box UX → background panel. Both ultimately write to background-clip, and a warning when there's a conflict seems reasonable.

There's no rush to land this, so happy to wait for design input before settling on the right UI direction.

In the meantime, I might see if I can throw up a quick PoC on splitting the concerns.

That said, I'd push back slightly on calling background-clip a hack. It's the established browser mechanism for this and has been for a long time. Even if CSS for text gradients evolves, I wouldn't expect background clip to go away soon. Especially, as the other methods of background clipping would still have their uses.

I don't mean background-clip being deprecated or anything, but other ways of adding gradients to text may become available.

But my main concern here is with exposing background-clip as a tool in the UI. Aside from the text gradient, it doesn't feel useful. Anyone wanting to apply a background color to the content box only can achieve similar effects by using margins instead of padding, so as a control background-clip doesn't add much value in itself. Is it worth the extra complexity introduced by a new block support? Personally I don't think so.

It would be good to have @WordPress/gutenberg-design opinions on this before proceeding.

Anyone wanting to apply a background color to the content box only can achieve similar effects by using margins instead of padding, so as a control background-clip doesn't add much value in itself.

I'm not sure margins are a reliable substitute here.

Padding creates space inside the border, margins outside it. So as soon as a block has a visible border, you can't replicate padding-box or content-box clipping with margins. The border would need to live on a separate wrapper element, which means extra markup and an additional block to work around the limitation.

Then there's border-box clipping with dashed or dotted borders, which is a unique visual effect with no workaround at all.

Is it worth the extra complexity introduced by a new block support? Personally I don't think so.

It's worth noting that a new block support is needed either way.

Even if we only ever expose the text gradient use case, that still requires a new block support whether it's under the banner of the color group of supports or background.

It still requires background-clip under the hood to so the question is really if there's any benefit in exposing the additional box clipping values on top of that, and I think for some theme authors building more expressive layouts it is.

The UI concern is real, though, and I agree that surfacing background clip directly isn't ideal for most cases.

I'm exploring that separately at the moment, the idea being that the text gradient use case gets a friendlier home in the colour panel and the box-clipping values only appear if a theme explicitly opts into them. So in practice, most users would never encounter a "background clip" control at all other than the text gradient control.

Then there's border-box clipping with dashed or dotted borders, which is a unique visual effect with no workaround at all.

I can imagine padding-box in particular being useful. I'm just looking at the examples at https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/background-clip

This is cool stuff. To be reductive, yes we definitely want for it to be trivial to apply gradients to apply to just the text, like this.

I also appreciate the broader ping, and the discussion already about this element, which I tend to echo:

This is a very complicated UI, and unless you know what padding-box, border-box, and background clip do, this will not be intuitive for very many people to use, and it most likely will not be easily with someone with an "I want to add a gradient to just the text" job in mind.

In that sense, I see two paths forward for landing this, but would appreciate broader input by those already pinged.

1. Embrace the advanced nature of background clip.
   The path this PR is already on. We need to consider the full spectrum of where border-box, padding-box, and background-clip features are useful, so we add this feature not just for block background. And we cast it as an advanced feature, definitely not shown by default (i.e. Advanced panel, or "add via ToolsPanel" disclosure), and add verbose help text. Patterns with text gradients already applied could still be a discovery mechanism, and theme designers can benefit.l
2. We rethink the feature as not about background-clip, but about text gradients
   This is an alternate approach that abstracts away padding-box/border-box/background-clip as just elements in a feature. Similar to "fit text", we'd need to think of a way to package this up that is simle and mostly intuitive.

For us to decide between the two, we'd need to take inventory of all the different ways the clip options can be used to create interesting designs. If it presents a compelling picture, we can go that way.

But absent that, 2 resonates in that it could possibly be as simple as this, which is arguably what is already being proposed:

I.e. add "gradient" as a tab on the Text color control.

A proof of concept is taking shape, though a number of problems were encountered while trying to build the combined text gradient control on top of color.gradient. The main issue is that color.gradient uses the background CSS shorthand, which can't be updated simultaneously with background-clip to produce the text gradient effect. Attempting to do so throws errors in the editor.

The proof of concept in #76171 addresses this by building on the proposed background.gradient support from #75859 instead.

There are still a number of rough edges in the UI so it isn't ready for demo or testing yet, but should be by later this week or early next.

One consideration worth raising: combining the background gradient and background clip into a single text gradient control removes the ability to clip a background image to text rather than a gradient. While testing, this turned out to produce some interesting aesthetics, particularly on large, chunky headings.

Once the proof of concept is more fleshed out, it would be worth evaluating whether the hybrid approach strikes the right balance between a streamlined text gradient flow and split controls (background image + background clip) for clipping a background image to text

combining the background gradient and background clip into a single text gradient control removes the ability to clip a background image to text rather than a gradient

It would be very cool to clip to an image. I'm just speaking for myself 😄

building on the proposed background.gradient support from #75859 instead.

This is pretty out there, but this reminds me of this idea: #60401 (comment)

background-image can have multiple stacked layers, and combined with opacity can open up some truly funky designs.

ses the background CSS shorthand, which can't be updated simultaneously with background-clip to produce the text gradient effect. Attempting to do so throws errors in the editor.

This is an early morning vague thought, I've no idea if relevant. But you could:

element {
	background: ...;
	background-clip: ...;
}

I.e. you don't have to put the clip part inside the shorthand selector, it can still exist separately to it, so long as it's below the shorthand declaration. I use this often with things like background and background-position.

Adding a background image is certainly interesting. But it's a difficult balance we're trying to strike here; the ability to add a "gradient" tab to the color panel seems so straight-forward and relatively intuitive, that I think it will make an excellent UI for this. Whereas the alternative can very easily get complex, UI wise. It's also arguably a bit of an edge-case to use images for this, so I'd personally be comfortable relegating this to requiring custom CSS for now.

However, and connecting back to #38577, one option to explore in the future, would be to add a 3rd tab, "Pattern" (or "Image") to the text color flyout, which would let you pick from a couple of bundled pattern images, or pick your own. Provided we could find the space for it (not much room for more tabs) and phrasing, that could unlock the UI for it. I think it'd be fine to explore, but I'd still keep it separate for now. Is that fair?

Just to be clear, I'm fully on board with adding a gradient tab to the Color panel's text section. The questions are really about what it builds on and how much of the underlying functionality we expose.

I.e. you don't have to put the clip part inside the shorthand selector, it can still exist separately to it, so long as it's below the shorthand declaration.

Thanks @jasmussen. The issue isn't about CSS declaration order, though. Block support styles are applied as React inline style objects, and React throws a runtime error when a style object contains both a shorthand property and a longhand it covers, in this case background and background-clip. There's no cascade to exploit here, in my understanding.

There are actually two separate questions. The first is which gradient support the text gradient control should build on. The second is whether theme authors should have access to the full background-clip functionality we're building anyway, beyond just the text gradient use case. The PoC in #76171 is exploring both.

On the first question, a few things worth laying out:

1. color.gradient conflicts with background image support due to its use of the background shorthand. This is a known limitation and the reason background.gradient in Block Supports: Add background gradient support that can combine with background images #75859 was proposed.
2. That same conflict is what makes building text gradient on top of color.gradient problematic. We'd be adding a new feature on foundations we've already identified as needing replacement.
3. Building on background.gradient also opens up more design freedom, since a text gradient could still be combined with a background image.

On the second question, the tradeoff with background.gradient is that it lives in the Background panel while also being settable via the Color panel's text gradient control, which requires some UX coordination between the two. But if we're solving that coordination problem for the gradient control, the same approach can be applied to a background.backgroundClip control, giving theme authors and block developers flexibility to expose as much or as little of the clipping functionality as they need. The base theme.json could disable the background clip UI by default, making it a deliberate opt-in for theme authors rather than something end users encounter unexpectedly.

On the image clipping point, agreed it's a niche case for now, and custom CSS is a reasonable fallback. The "Pattern/Image" tab idea is worth keeping in mind for later. The main concern is that collapsing clip into the gradient control and the color block supports early would make it harder to surface image clipping when the time comes.

So yes, broadly fair, with the caveat that the path to a gradient tab in the Color panel probably runs through background.gradient rather than color.gradient.

I hope all that makes sense 🤞

Building on background.gradient also opens up more design freedom, since a text gradient could still be combined with a background image.
the tradeoff with background.gradient is that it lives in the Background panel while also being settable via the Color panel's text gradient control, which requires some UX coordination between the two.
the caveat that the path to a gradient tab in the Color panel probably runs through background.gradient rather than color.gradient.

I have a bias toward fixing the background/background-* conflict, which has been reported in lots of places.

If it can be done under the hood, and it allows us to tread lightly in the UI and open up more design options for discussion I'm all for it!

Thanks for the laying out the issues and the great discussion 🙇🏻

Closing this PR in favour of #76171 which is based off #75859 so we can avoid the errors thrown due to color.background's use of the shorthand background CSS property.

#76171 also iterates on the UI discussions started here.