WordPress 7.1: Block visibility configurable breakpoints and theme.json integration

[ramonjd]

Important

This is the first version of this issue - it may change in scope after WordPress 7.0.

Follow-up to:

• WordPress 7.0: iteration issue for add option to hide blocks based on screen size #73776
• Add option to hide blocks based on screen size #72502

Tracking the next layer of work to make block visibility configurable by themes and extensible for future responsive features.

Context

Block visibility ships in WordPress 7.0 with three hardcoded viewport sizes: Mobile (≤480px), Tablet (480px–782px), Desktop (>782px). These values are duplicated across PHP (lib/block-supports/block-visibility.php) and JS (packages/block-editor/src/components/block-visibility/constants.js), with no connection to theme.json or the existing SCSS breakpoints in packages/base-styles/_breakpoints.scss.

The scope for 7.0 was intentionally narrow to ship on time, but the hardcoded nature creates limitations:

• Themes cannot define their own breakpoints to match their design systems.
• The breakpoint values differ from common frameworks and from WordPress's own admin breakpoints (600px, 782px).
• The viewport definitions in the editor (preview dropdown) and in block visibility are separate constants with no shared source of truth (noted as a @todo in constants.js).
• The style engine is bypassed for display property handling — a KSES filter allowlists display as a workaround (lib/compat/wordpress-7.0/kses.php).
• There is no way for themes to disable block visibility or control it per block type, unlike other block supports.

Block visibility is the first feature to generate per-block CSS within media queries. Establishing a solid, centralized foundation now — before more viewport-aware features arrive — avoids retrofitting later. This work does not implement responsive editing of other block properties, but it should not preclude it either.

Goals (to be decided)

1. Centralize breakpoint definitions (TBD)

Viewport sizes are currently defined independently in at least four places:

Location	Values	Format
lib/block-supports/block-visibility.php	480px, 782px	PHP array with name, slug, size
packages/block-editor/.../constants.js	desktop, tablet, mobile (no pixel values)	JS object with label, icon, key
packages/editor/.../preview-dropdown/index.js	Desktop, Tablet, Mobile	Inline array with labels
packages/base-styles/_breakpoints.scss	480px, 600px, 782px, 960px...	SCSS variables

These need to converge on a single canonical definition. The likely path is PHP (reading from theme.json with defaults) passed to JS via editor settings, but the exact mechanism needs discussion.

2. Theme-configurable breakpoints in theme.json

Extend the theme.json schema so themes can define viewport breakpoints. The exact schema location and shape need discussion — key design questions include:

• Where in the theme.json structure do breakpoints belong? (Top-level settings? Under settings.layout? A new settings.responsive key?)
• Should themes be able to define more or fewer than three breakpoints? What are the UI constraints?
• How do theme-defined breakpoints interact with fluid typography and spacing values that already provide responsive behavior via clamp()?
• What are the sensible defaults, and should they match the current visibility values (480px, 782px) or align with the broader WordPress admin breakpoints (600px, 782px)?

Elaborated upon in the following comment: #75707 (comment)

3. theme.json settings to control block visibility

Relies on agreement of JSON structure with 2. Theme-configurable breakpoints in theme.json

Allow themes to disable block visibility globally or per block type, following the same patterns as other block supports (e.g., color, spacing, typography). The mechanism should be consistent with how themes already opt in or out of block support features.

Per-block-type opt-out via block.json already works today, e.g., block_has_support( $block_type, 'visibility', true )

Related comment: #75707 (comment)

4. Bundling CSS with global styles rather than at run time in block supports

Depends on 2. Theme-configurable breakpoints in theme.json

The media query generation logic should live in a place where other features can reuse it, that implies WP_Theme_JSON generating the viewport utility classes as part of the global stylesheet — not embedded in block visibility rendering. Following this, whether the breakpoint-to-media-query mapping should be a style engine concern, a block supports concern, or a theme.json processing concern.

How to do this? Inline in WP_Theme_JSON adds to bloat. Does the style engine need to be extended to handle this as an exception, e.g., as with fluid typography?

Related comment: #75707 (comment)

5. Miscellaneous fixes and enhancements

• Block Visibility: Selected block remains selected when switching viewport preview #76275
• Component's Popover Toolbar simplified for Tablet/Mobile blocks #76733
• Component badge for hidden block should display for all resolutions, not only Desktop #76730

Open questions

• Breakpoint format: Should breakpoints use range syntax (width <= 480px) as they do now, or min/max-width for broader browser compatibility? The current implementation uses CSS range syntax which is modern but relatively new.
• Attribute validation: If breakpoints become theme-configurable, how do we validate blockVisibility.viewport attribute keys against the available breakpoints? What happens when a theme changes its breakpoints and existing content references old slugs?
• Container queries: Some community discussion (Blocks: States #57719) suggests container queries may be more appropriate than viewport queries for block-level responsiveness. Should the breakpoint infrastructure account for container queries as a future possibility, or is that a separate concern?

Stretch goals

• Convert block visibility JS files and constants to TS. See useBlockVisibility: consolidate useMemo calls to the output object #75120 (comment) and Block visibility based on screen size: add rules to hide on viewport size #74379 (comment)

Assumptions and risks

The scope will be affected by:

• any necessary UI/UX enhancements in response to feedback
• tech debt or unblocking refactoring

Out of scope

• Responsive editing of block properties (font-size, spacing, layout direction, etc.) — see #19909.
• Block states (hover, focus, viewport as triggers for property changes) — see #57719.
• User-configurable breakpoints in the site editor UI — theme.json first, UI later.
• Extending visibility to non-viewport criteria (user roles, time-based rules, etc.).

Related

• #73776 — WordPress 7.0 block visibility iteration
• #72502 — Original block visibility feature issue
• #19909 — Responsive previewing and device-specific editing
• #57719 — Block states
• #73888 — Responsive editing mode proof of concept
• #39281 — Related possibly to "states" and how to store responsive styles for blocks

[ramonjd]

Theme-configurable breakpoints in theme.json

Looking at scope and MVP for 7.1 for this specific item.

Here's what I'm currently proposing:

• settings.responsive.viewports in theme.json. Themes can ONLY override the size values of the mobile and tablet breakpoints (e.g. 600px instead of 480px)
• Validation in WP_Theme_JSON at parse time. Invalid theme viewports fall back to WP defaults silently
• block-visibility.php block supports merges theme sizes into defaults by slug at render time
• new hook in block-editor that reads resolved breakpoints from useSettings('responsive.viewports') and merges overrides into the constants defaults
• useBlockVisibility now uses dynamic useMediaQuery calls built from the resolved sizes, replacing the hardcoded SCSS-backed useViewportMatch

A test PR:

• Add/configurable viewport values theme json #76475

Notes for future responsive style properties

The breakpoint definitions live at settings.responsive.viewports. These are neutral and not tied to block visibility.
Any future feature (responsive font-size, padding, color) can access the same values via useSettings('responsive.viewports') and get the same resolved, theme-aware sizes.

This work does not preclude responsive style properties down the track (for responsive editing), e.g., block level styles in theme.json or global styles:

{
  "styles": {
    "blocks": {
      "core/paragraph": {
        "typography": { "fontSize": "1rem" },
        "responsive": {
 		 "viewport": {
          "mobile": {
            "typography": { "fontSize": "0.875rem" }
          }
		}
        }
      }
    }
  }
}

An alternative could be a new level in the styles hierarchy:

{
  "styles": {
    "responsive": {
      "viewport": {
        "mobile": {
          "blocks": {
            "core/heading": {
              "typography": { "fontSize": "1.25rem" }
            }
          }
        }
      }
    }
  }
}

Deferred/seperate work

• Arbitrary viewport count (currently fixed to mobile/tablet/desktop slugs) — schema and validation changes are minimal to unlock this later
• Dynamic preview canvas sizing to match theme breakpoints. Essentially wiring theme breakpoints into the dropdown. This affects canvas size and potentially touches the editor preview frame.
• SCSS breakpoint consolidation (_breakpoints.scss still hardcoded)
• use-viewport-sync.js VALID_DEVICE_TYPES still hardcoded
• TypeScript conversion of block visibility files
• Container query considerations remain a separate concern

[ramonjd]

Style engine integration

I think it makes sense to have WP_Theme_JSON::get_stylesheet() generate the viewport utility CSS using wp_style_engine_get_stylesheet_from_css_rules with rules_group, the same way block-visibility.php does now.

But it would be called once during global stylesheet generation rather than per-block render. The style engine would handle the CSS string construction;, and WP_Theme_JSON provides the viewport definitions.

[DenisStetsenko]

Themes can ONLY override the size values of the mobile and tablet breakpoints

As we are so close to this important addition, wouldn't it make sense to include additional Desktop breakpoints?

• Bootstrap has Large(≥992px),Extra large(≥1200px), and Extra extra large(≥1400px)
• Tailwind CSS has lg(≥1024px), xl(≥1280px), and xxl(≥1536px)

Having an option to control mobile, tablet, and desktop breakpoints would significantly improve layout flexibility. It would also give theme developers more control over widescreen layouts without requiring custom workarounds or additional CSS overrides.

Those are my two cents on it.

[ramonjd]

As we are so close to this important addition, wouldn't it make sense to include additional Desktop breakpoints?

@DenisStetsenko Yes! I'm thinking MVP right now. There are layers at play here.

Permitting additional breakpoints in theme.json and generating the requisite CSS and classnames for the frontend is not the speed hump.

Rather, it's how we translate them to the editor UI, especially how they relate, if at all, to the current viewport preview dropdown.

My assumption is that it'll all work dynamically based on the theme.json entries, that is, the editor allows you to choose and preview the viewport widths defined by the user.

It might mean refactoring or just getting rid of the theme preview dropdown.

Ultimately I think what you state is the end goal for sure. There are always rabbit holes and my approach is tip toe around them. 😄