Custom Breakpoints in Block Themes, Without CSS

Maintaining a block theme has meant keeping two systems in your head: the parts you configure in theme.json, and the media queries you hand-write in a stylesheet because theme.json had no concept of a viewport. WordPress 7.1, released 19 August 2026, closed most of that gap. A core dev note published on 5 August 2026 on responsive block styles and configurable viewports sets out how.

What you can now express without a stylesheet

Styles take two new keys, @mobile and @tablet, nested inside a style definition. A block needing less padding on a phone gets it declared in place rather than in a media query three files away:

"@mobile": { "spacing": { "padding": { "top": "1rem" } } }

Coverage is wider than the syntax suggests. Per the dev note, responsive styles apply to all block types, and their block style variations, using core block supports — typography, colour, background, border, dimensions, spacing and layout. That is most of what a theme declares. It is not everything: anything expressed as raw CSS, and anything a block implements outside core supports, still needs a stylesheet.

Defining your own breakpoints

Before 7.1 the breakpoints were core’s and they were not yours. Now a theme sets them at the top level under settings.viewport:

"settings": { "viewport": { "mobile": "30rem", "tablet": "45rem" } }

Three rules govern what that file will accept, and all three produce confusing results if you learn them by trial and error.

• The defaults are what your styles compile to if you do not override them. Mobile resolves to @media (width <= 480px) and tablet to @media (480px < width <= 782px). That 782px figure will look familiar to anyone who has written WordPress admin CSS.
• Values must use px, em or rem. CSS functions and percentages are rejected rather than silently ignored, which is the better of the two failure modes. If a breakpoint change appears to do nothing, check the unit first.
• Viewport and pseudo-state keys nest, viewport outermost. A hover style that only applies on tablet is expressed by nesting the pseudo-state inside the viewport key, not the other way round.

There is no @desktop, and that is deliberate

The dev note is explicit that no @desktop key exists. The base style applies at every width unless a viewport key overrides it, which makes the system mobile-last rather than mobile-first: you write the wide layout as the default and narrow it downwards.

This catches people who have spent years writing min-width queries. Under that habit the base styles are the phone styles and everything larger is an addition. Here the base is the general case. Porting an existing stylesheet by mechanically converting each media query will produce specificity that fights itself, and the cleaner route is to decide what the unqualified style should be and then subtract.

The layout-stability angle

Hand-written media queries accumulate predictably. A rule gets added for one template, a second for a page that broke, a third to undo the first two, and after a year the mobile layout is defined in four files by rules nobody can safely delete. Consolidating them into theme.json is a maintenance win, but there is a measurement consequence too.

A breakpoint mismatch is a layout shift. When a component’s width, padding or font size is set by one rule and corrected by another that arrives later — or when a breakpoint boundary disagrees with the width at which an image’s intrinsic sizing changes — elements move after first paint, and that movement is what Cumulative Layout Shift records. Expressing the responsive rules in one compiled source rather than several cascading ones removes a class of that problem rather than hiding it. It is also the kind of thing that only shows up on a real device: a shift at 420px is invisible on a desktop test, which is the same blind spot discussed in what Search Console dropped on mobile usability, and it now has to be caught by your own testing.

What is still coming, and why not to over-build now

7.1 covers core blocks and core block supports. Third-party blocks that implement their own styling are not part of it. The roadmap to WordPress 7.2, published 18 September 2026, names expanded responsive styling and custom state support among its goals for the December release, which is where a public API for third-party blocks is expected to land.

The practical reading for a theme developer is to migrate core-block responsive rules into theme.json now, since that surface is stable and shipped, and to leave custom blocks on their existing stylesheets rather than building a private mechanism that a core API will make redundant in a quarter. The general picture of where block themes currently stand is covered in Full Site Editing in 2026, and the global settings and styles documentation remains the reference for what the file accepts. Fewer stylesheets is also fewer render-blocking requests, which is one of the smaller wins listed in WordPress SEO and performance and worth taking while you are in the file anyway.