Background Gradient Block Support Ships in WordPress 7.1

Every WordPress release has one small design-tools change that looks trivial in the dev note and then quietly saves you a child theme. This week it is the new background.gradient block support in 7.1. The headline is boring: blocks can now hold a gradient in the Background panel. The reason it matters is that the gradient finally sits on background-image instead of the background shorthand, so it stops fighting the image you set right above it.

I have been writing “gradient over hero photo” CSS into child themes since the block editor shipped. Every agency I know has a snippet for it. Every one of those snippets exists because color.gradient was wired to the wrong CSS property in 2019 and nobody wanted to be the person who broke the migration. That is what got fixed here, and it got fixed in the additive, opt-in way that keeps existing themes untouched.

This is the same maturity walk the block editor did with border-radius, box-shadow, and letter-spacing. Custom CSS first, then theme.json, then presets, then a proper inspector control. Background gradient is on step three as of 7.1. Not the finish line, but the step where it starts paying for itself.

What is actually new

Aaron Robertshaw’s Make/Core dev note “New Block Support in WordPress 7.1: Background Gradient” (July 26, 2026) documents the surface. A new background.gradient support key, opted in via block.json, gives a block a gradient picker inside the Background panel of the block inspector. Same picker component you already know from the color panel, moved to where the image control lives.

The change under the hood is the one that matters. color.gradient serialised to the background CSS shorthand, which resets every other background property in the same rule. That is why setting a gradient wiped the image. background.gradient serialises to background-image, so gradient and image render as comma-separated values: background-image: linear-gradient(135deg, #000 0%, #fff 100%), url('/hero.jpg');. The gradient sits on top of the image. Both stay there.

Five core blocks opt in for the 7.1 GA on August 19: core/group, core/accordion, core/pullquote, core/post-content, and core/quote. When a block has background.gradient enabled, the gradient tab in the Color panel is suppressed so editors do not see two conflicting gradient controls on the same block. Gradient presets keep resolving to the same CSS custom properties (var(--wp--preset--gradient--vivid-cyan-blue)), so any existing preset stack keeps working.

The plumbing shipped as Gutenberg PR #75859 back on April 1, 2026, closing issue #32787, opened by Justin Tadlock in June 2021. Nearly five years between “this is set on the wrong CSS property” and “here is a public API that fixes it.” That is the WordPress governance layer working exactly as designed — slow, additive, backwards compatible, no theme opts in, no theme opts out, no theme breaks. Robertshaw’s note is explicit: “no existing blocks are broken, and no action is required for most blocks and themes.”

Two things are explicitly not shipping in 7.1. First, this is not a migration. core/cover and the other blocks that still lean on color.gradient keep behaving as they always did. Robertshaw calls out that the new support “lays the groundwork for eventually migrating gradient handling from color.gradient to background.gradient across blocks” — future release, not this one. Second, the related text-gradient work (background-clip: text, tracked in PR #76171) is still in draft. Do not build against it yet.

Why it matters for WordPress and WooCommerce people

The gradient-over-image pattern is the single most common hero-section design brief on WooCommerce stores. Product hero, dark linear-gradient from bottom for contrast, headline and CTA sit on top. On agency work I have shipped over the last five years, this recipe has lived in one of four places: additional CSS in the customiser, a child theme’s style.css, a page-builder module’s inline styles, or (worst) a shortcode wrapper around the Cover block. All four are technical debt. All four make theme migration expensive.

Moving the token into theme.json makes it portable. It travels with the theme file. It is discoverable through wp theme.json tooling. It shows up in Global Styles as a real setting, not a random CSS snippet. When you rebuild the site on a different theme in three years, the gradient comes with. That is the whole point of the design-token direction the block editor has been walking since 5.9.

The five adopting blocks are also the right ones for the pattern. core/group is where most hero sections actually live. core/post-content lets you layer a gradient behind body copy on single templates. core/pullquote and core/quote give designers a gradient-on-photo blockquote treatment without a custom block. core/accordion is the odd one on the list but makes sense — FAQ sections on WooCommerce product pages routinely want a subtle brand-colour wash. None of these needed a plugin. They needed a properly wired CSS property.

What I would do (or not do) about it

Do this week: grep every child theme, custom stylesheet, and additional-CSS block for background-image: declarations that combine a gradient and a url(). Those are your candidates to migrate into theme.json under styles.blocks.core/group.background.gradient (or whichever of the five blocks fits) after 7.1 GA on August 19. Do not migrate the day of GA. Do the audit now, land the migration on a scheduled window in early September once 7.1.1 has landed and the dust has settled.

Test on Beta 3 or the current 7.1 RC candidate in a Playground blueprint or a staging clone, not production. Drop a background.gradient value on a Group block, set a background image on the same block, verify the render in the editor and on the front end. Confirm the CSS output matches the byte-for-byte pattern in the dev note. If you have existing production CSS for the same visual, run it side by side and confirm the diff is empty. That is the migration confidence you need before you delete the snippet.

Do not migrate any block using core/cover today. Cover still uses color.gradient. If it moves later, core will handle the migration in that block’s own PR — do not front-run it with a plugin or filter that swaps the serialisation. Do not install a third-party plugin that adds a “gradient over image” inspector control to every block. Five core blocks now have it. The rest will follow at core’s pace. Any third-party control becomes technical debt the moment core ships its own.

Do not stack this on the WooCommerce 11.0 window. WooCommerce 11.0 lands July 28, WordPress 7.1 lands August 19, three weeks apart. Run WC 11.0 through staging first, land it on production, then move on to 7.1. Two triage queues on the same weekend is the fastest way to spend a weekend chasing regressions in the intersection instead of in either release.

The broader signal is the one worth writing down. Every design token that moves from a CSS snippet into theme.json is one less line of drift in the “random CSS” folder and one more design decision that lives inside the theme file, versioned with the rest of it. That is the design-system version of WordPress’s usual year-five governance story, and it is the reason theme migrations get cheaper release by release instead of more expensive.