Block visibility based on screen size: add backend block support

[ramonjd]

Related to #72502

Backport Core PR:

• Block visibility supports: implement block visibility based on breakpoints wordpress-develop#10629

What?

Implements backend support for responsive block visibility, allowing blocks to be hidden on specific viewport breakpoints (mobile, tablet, desktop) using CSS media queries.

Functionality is gated behind the gutenberg-hide-blocks-based-on-screen-size experiment flag. The existing boolean blockVisibility: false behavior works without the experiment enabled.

Clientside state is happening over in:

• Block visibility based on screen size: basic clientside state #74025

How?

This PR borrows approaches from #73735 and #73888 to implement the backend that:

• generates media queries based on block metadata
• applies the classname and enqueues the CSS via the style engine

Testing

Unit tests:

npm run test:unit:php:base -- --filter=WP_Block_Supports_Block_Visibility_Test

To test manually, enable the experiment:

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

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

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

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

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

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

<!-- wp:paragraph {"metadata":{"blockVisibility":{"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.

[github-actions]

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.

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

Co-authored-by: ramonjd <[email protected]>
Co-authored-by: PrathameshBhagat365 <[email protected]>
Co-authored-by: mtias <[email protected]>
Co-authored-by: tellthemachines <[email protected]>
Co-authored-by: andrewserong <[email protected]>

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

[ramonjd]

WP Core sync to come...

[github-actions]

Flaky tests detected in 168804b.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/20252320559
📝 Reported issues:

• [Flaky Test] should open and edit templates correctly when active_templates experiment is disabled #73743 in /test/e2e/specs/site-editor/template-id-format.spec.js

[PrathameshBhagat365]

Sanitize generated class names: use sanitize_html_class() (or sanitize_key()) when building 'wp-block-hidden-...'.
Restrict/validate breakpoints: only honor known breakpoint keys (array_intersect with defined breakpoints) to avoid mismatched counts and unexpected classes.
All-hidden check: compare hidden breakpoints against actual breakpoint keys (use intersection) before returning ''.
WP_HTML_Tag_Processor fallback: add a safe fallback if the class isn't available (careful regex or DOMDocument) so adding the class can't fail.
KSES shim loading: guard or document the compat/kses.php include (WP version check or comment) and add a unit test that toggles the experiment and asserts 'display' is added/removed from safe_style_css.
Style engine / !important: confirm the engine accepts '!important' values; prefer explicit API for importance or ensure the generated CSS is not stripped/altered.
Tests: add test for unknown breakpoint keys being ignored and for the WP_HTML_Tag_Processor fallback (if implemented).

[Copilot]

Pull request overview

This PR implements backend support for responsive block visibility, enabling blocks to be conditionally hidden at specific viewport breakpoints (mobile, tablet, desktop) using CSS media queries and the Style Engine. The feature is gated behind the gutenberg-hide-blocks-based-on-screen-size experiment flag, while maintaining backward compatibility for the existing boolean blockVisibility: false behavior.

• Generates viewport-specific CSS rules with media queries based on block metadata
• Adds visibility classes to blocks and enqueues styles via the Style Engine
• Includes comprehensive unit tests covering various breakpoint combinations and edge cases

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
phpunit/block-supports/block-visibility-test.php	Adds comprehensive test suite covering boolean visibility, viewport-based visibility with experiment flag, edge cases like empty/unknown breakpoints, and CSS generation verification
lib/block-supports/block-visibility.php	Implements core logic for parsing breakpoint visibility metadata, generating media query CSS rules, applying visibility classes, and handling the experiment flag
lib/compat/wordpress-7.0/kses.php	Adds 'display' property to safe CSS attributes list when experiment is enabled, required for inline styles
lib/load.php	Includes the new kses.php compatibility file in the WordPress 7.0 compatibility layer
backport-changelog/7.0/10629.md	Documents the backport reference to WordPress core PR

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[tellthemachines]

This is working well and generally LGTM, the only thing I'm not convinced about is the need for defining both max and min breakpoints (see below). This is assuming that we're shaping this in a way that will make it easy to build a theme.json setting on top of it.