Block visibility supports: implement block visibility based on breakpoints #10629

ramonjd · 2025-12-15T02:12:07Z

Note

The feature is still in an experiment in Gutenberg, so this PR is a placeholder for stabilization. See: WordPress/gutenberg#73994

This PR syncs the changes in WordPress/gutenberg#73994. It:

implements breakpoint visibility support in block rendering, allowing blocks to be hidden or shown based on defined breakpoints.
introduces the display property to the safecss_filter_attr function.

Unit tests:

npm run test:php -- --filter Tests_Kses 
npm run test:php -- --filter Tests_Block_Supports_Block_Visibility

Then copy and paste this into your post editor, publish and view the frontend.

<!-- wp:paragraph {"metadata":{"blockVisibility":{"viewport":{"mobile":false}}}} -->
<p>🔴 Hidden on MOBILE (≤479px) - You should see this on tablet and desktop only</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph {"metadata":{"blockVisibility":{"viewport":{"tablet":false}}}} -->
<p>🟡 Hidden on TABLET (480-959px) - You should see this on mobile and desktop only</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph {"metadata":{"blockVisibility":{"viewport":{"desktop":false}}}} -->
<p>🟢 Hidden on DESKTOP (≥960px) - You should see this on mobile and tablet only</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph {"metadata":{"blockVisibility":{"viewport":{"mobile":false,"desktop":false}}}} -->
<p>🟣 Hidden on MOBILE and DESKTOP - You should only see this on tablet (480-959px)</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph {"metadata":{"blockVisibility":{"viewport":{"mobile":false,"tablet":false}}}} -->
<p>🔵 Hidden on MOBILE and TABLET - You should only see this on desktop (≥960px)</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph {"metadata":{"blockVisibility":{"viewport":{"tablet":false,"desktop":false}}}} -->
<p>🟠 Hidden on TABLET and DESKTOP - You should only see this on mobile (≤479px)</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph {"metadata":{"blockVisibility":{"viewport":{"mobile":true,"tablet":true,"desktop":true}}}} -->
<p>✅ Visible on ALL breakpoints - You should always see this</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph {"metadata":{"blockVisibility":false}} -->
<p>❌ Completely HIDDEN (boolean false) - You should never see this</p>
<!-- /wp:paragraph -->

Kapture.2025-12-14.at.19.37.29.mp4

Make sure to test with the experiment off as well. The last item should never show with the experiment on and off.

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

github-actions · 2025-12-15T02:12:18Z

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 ramonopoly, westonruter, isabel_brison.

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

github-actions · 2025-12-15T02:30:09Z

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

The Plugin and Theme Directories cannot be accessed within Playground.
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.

westonruter · 2026-01-08T07:08:34Z

src/wp-includes/block-supports/block-visibility.php

+		 * Breakpoints as array items are defined sequentially. The first item's size is the max value.
+		 * Each subsequent item's min is calc(previous size + 1px), and its size is the max.
+		 * The last item's min is previous size plus 1px, and it has no max.


Can we avoid the 1px offset and instead use the range syntax for media queries? We switched to this in Performance Lab, as it addresses possible issues with media queries in sub-pixel scenarios: WordPress/performance#1696

Thanks for bringing that up @westonruter

I forgot about range - looks like it has decent support now.

What do you think @tellthemachines ?

looks like it has decent support now

Indeed: https://caniuse.com/css-media-range-syntax

Yes absolutely, let's give it a go!

Thanks folks, I'll make a start on this 🙇🏻

tests/phpunit/tests/block-supports/block-visibility.php

src/wp-includes/block-supports/block-visibility.php

ramonjd · 2026-01-09T01:29:50Z

src/wp-includes/block-supports/block-visibility.php

+		 * Breakpoints as array items are defined sequentially. The first item's size is the max value.
+		 * Each subsequent item's min is calc(previous size + 1px), and its size is the max.
+		 * The last item's min is previous size plus 1px, and it has no max.


Thanks for bringing that up @westonruter

I forgot about range - looks like it has decent support now.

What do you think @tellthemachines ?

ramonjd · 2026-01-09T01:30:40Z

src/wp-includes/block-supports/block-visibility.php

+		 * Each subsequent item's min is calc(previous size + 1px), and its size is the max.
+		 * The last item's min is previous size plus 1px, and it has no max.
+		 */
+		$breakpoints = array(


I wanted to also mention this idea raised by @t-hamano

This is a technical question, but in the future, how do you think about being able to hide blocks based on sources other than screen size (e.g. user role, time period)? If there's a chance that there could be multiple sources, it might be better to nest the metadata key for now,

Done in WordPress/gutenberg#74602

src/wp-includes/block-supports/block-visibility.php

…implement block visibility based on breakpoints. This update introduces the `display` property to the `safecss_filter_attr` function, enhancing CSS filtering capabilities. Additionally, it implements breakpoint visibility support in block rendering, allowing blocks to be hidden or shown based on defined breakpoints. Corresponding tests have been added to ensure functionality. See #64414.

…ty when all visibility breakpoints (mobile, tablet, desktop) are set to false.

…heet retrieval. This change ensures that the generated styles for mobile, tablet, and desktop breakpoints are returned without additional formatting, allowing for accurate assertions in the tests.

…ss values

…ign with design specifications. Adjust corresponding unit tests to reflect the new breakpoint values.

…mproved clarity. Update unit tests to reflect changes in breakpoint definitions for mobile, tablet, and desktop visibility rules.

…lues.

…date media query generation to ensure accurate handling of viewport sizes.

ramonjd self-assigned this Dec 15, 2025

ramonjd added the enhancement label Dec 15, 2025

ramonjd mentioned this pull request Dec 15, 2025

Block visibility based on screen size: add backend block support WordPress/gutenberg#73994

Merged

github-actions bot mentioned this pull request Dec 23, 2025

PHP backports for WP 7.0 WordPress/gutenberg#74043

Open

ramonjd force-pushed the add/block-visibility-at-breakpoints-supports branch from bf1d22c to 2835818 Compare January 6, 2026 23:28

westonruter reviewed Jan 8, 2026

View reviewed changes

ramonjd commented Jan 9, 2026

View reviewed changes

westonruter reviewed Jan 9, 2026

View reviewed changes

src/wp-includes/block-supports/block-visibility.php Outdated Show resolved Hide resolved

src/wp-includes/block-supports/block-visibility.php Outdated Show resolved Hide resolved

This was referenced Jan 12, 2026

Block visibility support: use CSS range syntax for media queries WordPress/gutenberg#74526

Merged

Block visibility supports: refactor metadata to use nested structure WordPress/gutenberg#74602

Merged

ramonjd force-pushed the add/block-visibility-at-breakpoints-supports branch from 928a9eb to 2190cc5 Compare January 16, 2026 01:12

ramonjd added 14 commits January 16, 2026 18:14

removing unnecessary sanitization and improving class name generation

6dc5ced

This commit introduces a new test to verify that block content is emp…

95cd611

…ty when all visibility breakpoints (mobile, tablet, desktop) are set to false.

Sync with WordPress/gutenberg#73994

4f06d67

whoops

2818366

Update block visibility tests to disable CSS prettification in styles…

f1541d7

…heet retrieval. This change ensures that the generated styles for mobile, tablet, and desktop breakpoints are returned without additional formatting, allowing for accurate assertions in the tests.

Adjusted max-width values from 599px to 479px to match breakpoints.sc…

173a101

…ss values

Update block visibility breakpoints for mobile and tablet sizes to al…

cf06337

…ign with design specifications. Adjust corresponding unit tests to reflect the new breakpoint values.

Refactor block visibility media queries to use CSS range syntax for i…

0383b98

…mproved clarity. Update unit tests to reflect changes in breakpoint definitions for mobile, tablet, and desktop visibility rules.

Sync WordPress/gutenberg#74602

5a0e25b

Use "viewport" instead of breakpoint to refer to metadata keys and va…

3885f81

…lues.

Fix broken test (wrong fixture)

dd04b3b

Sync with WordPress/gutenberg#74679

6252a81

Refine comments and logic in block visibility support for clarity. Up…

0ca2322

…date media query generation to ensure accurate handling of viewport sizes.

ramonjd force-pushed the add/block-visibility-at-breakpoints-supports branch from b2b2ff4 to 0ca2322 Compare January 16, 2026 07:14

Block visibility supports: implement block visibility based on breakpoints #10629

Are you sure you want to change the base?

Block visibility supports: implement block visibility based on breakpoints #10629

Conversation

ramonjd commented Dec 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Dec 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Dec 15, 2025

Test using WordPress Playground

Some things to be aware of

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ramonjd commented Dec 15, 2025 •

edited

Loading

github-actions bot commented Dec 15, 2025 •

edited

Loading