Responsive block styles land with configurable breakpoints

WordPress 7.1 introduces responsive style states for blocks. Styles can now be defined for Tablet and Mobile viewports both through Global Styles for each block type and on individual block instances. They can be applied to all block types (and their block style variations) that use core block supports such as typography, color, background, border, dimensions, spacing, and layout.

The default style remains the base style and applies at every viewport. Tablet and Mobile styles override that base within their respective breakpoint ranges.

It is now also possible to define custom values for the Tablet and Mobile viewports, using px, em or rem units.

Defining responsive block styles in `theme.json`

"styles": {
		"blocks": {
			"core/group": {
				"spacing": {
					"padding": {
						"top": "3rem",
						"right": "3rem",
						"bottom": "3rem",
						"left": "3rem"
					}
				},
				"@mobile": {
					"spacing": {
						"padding": {
							"top": "1rem",
							"right": "1rem",
							"bottom": "1rem",
							"left": "1rem"
						}
					}
				}
			}
		}
	}

Responsive and pseudo-states are nested from viewport to pseudo-state:

"styles": {
		"blocks": {
			"core/button": {
				"@mobile": {
					":hover": {
						"color": {
							"background": "var:preset|color|contrast",
							"text": "var:preset|color|base"
						}
					}
				}
			}
		}
	}

Block instance attributes

Responsive styles for an individual block are stored in the block’s existing style attribute, using the same @mobile and @tablet keys as Global Styles:

<!-- wp:paragraph {"style":{"@mobile":{"typography":{"fontSize":"1rem"}}}} -->
<p>Text with a responsive font size.</p>
<!-- /wp:paragraph -->

On the frontend, WordPress generates media-query-scoped CSS for the responsive values and adds a stable, generated class to the rendered block. Non-layout per-instance state declarations are marked `!important` so they can override the block’s default inline styles. Responsive layout values and `blockGap` are processed by the existing layout support and scoped with the block’s generated container class.

Configurable breakpoints

WordPress provides two responsive style breakpoints by default:

State

Media query

@mobile

@media (width <= 480px)

@tablet

@media (480px < width <= 782px)

There is no @desktop style key. The block’s default style is the desktop/base style and continues to apply at smaller sizes for any property that is not overridden.

Themes can customize the breakpoint widths with the new top-level settings.viewport values:

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

This produces the following ranges:

@media (width <= 30rem) { /* Mobile */ }
@media (30rem < width <= 45rem) { /* Tablet */ }

Breakpoint values must be non-negative numeric lengths using px, em, or rem. CSS functions, percentages, unitless values, and other units are ignored.

If only one valid breakpoint is configured, it keeps its viewport name and uses a single maximum-width query. If neither value is valid, the defaults are used. When both are valid but the Tablet value is smaller than or equal to the Mobile value, only the Mobile breakpoint is used.

The configured viewport widths are used by responsive block styles and block visibility, and are previewable via the editor’s device preview.

settings.viewport is a top-level setting. It cannot be configured separately for individual block types.

Opting out of responsive editing

Sites that need to prevent users from making viewport-based styling changes can turn off responsive style editing with the responsiveEditingEnabled editor setting, which defaults to true:

function example_disable_responsive_editing( $settings ) {
	$settings['responsiveEditingEnabled'] = false;
	return $settings;
}
add_filter( 'block_editor_settings_all', 'example_disable_responsive_editing' );

When it is false, both entry points for choosing a viewport are removed: the “Responsive styles” toggle in the Editor’s View menu, and the “Viewport” group in the “States” dropdown in Global Styles. Device previews still work, and pseudo states such as Hover remain available.

The setting governs the editing interface only. Responsive styles already saved in theme.json, in Global Styles, or in a block’s style attribute are left untouched, and the media-query CSS described above is still generated for them, so existing content renders exactly as before both in the Editor and on the front end.

Reviewed by @tyxla; props @ramonopoly, @wildworks

#7-1-3, #dev-notes, #dev-notes-7-1