{"id":124535,"date":"2026-08-05T06:50:06","date_gmt":"2026-08-05T06:50:06","guid":{"rendered":"https:\/\/make.wordpress.org\/core\/?p=124535"},"modified":"2026-08-06T18:22:34","modified_gmt":"2026-08-06T18:22:34","slug":"responsive-block-styles-and-configurable-viewports-in-wordpress-7-1","status":"publish","type":"post","link":"https:\/\/make.wordpress.org\/core\/2026\/08\/05\/responsive-block-styles-and-configurable-viewports-in-wordpress-7-1\/","title":{"rendered":"Responsive block styles and configurable viewports in WordPress 7.1"},"content":{"rendered":"

WordPress 7.1 introduces responsive style states for blocks<\/a>. Styles can now be defined for Tablet and Mobile viewports both through Global Styles for each blockBlock<\/span> Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.<\/span><\/span><\/span> type and on individual block instances. They can be applied to all block types (and their block style variations) that use core block supports<\/a> such as typography, color, background, border, dimensions, spacing, and layout.<\/p>\n\n\n\n

The default style remains the base style and applies at every viewport. Tablet and Mobile styles override that base within their respective breakpoint ranges.<\/p>\n\n\n\n

It is now also possible to define custom values for the Tablet and Mobile viewports, using px<\/code>, em<\/code> or rem<\/code> units.<\/p>\n\n\n\n

Defining responsive block styles in<\/strong> `theme.jsonJSON<\/span> JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML.<\/span><\/span><\/span>`<\/strong><\/h2>\n\n\n\n
\"styles\": {\n\t\t\"blocks\": {\n\t\t\t\"core\/group\": {\n\t\t\t\t\"spacing\": {\n\t\t\t\t\t\"padding\": {\n\t\t\t\t\t\t\"top\": \"3rem\",\n\t\t\t\t\t\t\"right\": \"3rem\",\n\t\t\t\t\t\t\"bottom\": \"3rem\",\n\t\t\t\t\t\t\"left\": \"3rem\"\n\t\t\t\t\t}\n\t\t\t\t},\n\t\t\t\t\"@mobile\": {\n\t\t\t\t\t\"spacing\": {\n\t\t\t\t\t\t\"padding\": {\n\t\t\t\t\t\t\t\"top\": \"1rem\",\n\t\t\t\t\t\t\t\"right\": \"1rem\",\n\t\t\t\t\t\t\t\"bottom\": \"1rem\",\n\t\t\t\t\t\t\t\"left\": \"1rem\"\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}<\/code><\/pre>\n\n\n\n
Responsive and pseudo-states are nested from viewport to pseudo-state:<\/p>\n\n\n\n
\"styles\": {\n\t\t\"blocks\": {\n\t\t\t\"core\/button\": {\n\t\t\t\t\"@mobile\": {\n\t\t\t\t\t\":hover\": {\n\t\t\t\t\t\t\"color\": {\n\t\t\t\t\t\t\t\"background\": \"var:preset|color|contrast\",\n\t\t\t\t\t\t\t\"text\": \"var:preset|color|base\"\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}<\/code><\/pre>\n\n\n\n
Block instance attributes<\/strong><\/h2>\n\n\n\n
Responsive styles for an individual block are stored in the block\u2019s existing style<\/code> attribute, using the same @mobile<\/code> and @tablet<\/code> keys as Global Styles:<\/p>\n\n\n\n
<!-- wp:paragraph {\"style\":{\"@mobile\":{\"typography\":{\"fontSize\":\"1rem\"}}}} -->\n<p>Text with a responsive font size.<\/p>\n<!-- \/wp:paragraph --><\/code><\/pre>\n\n\n\n
On the frontend, WordPress generates media-query-scoped CSSCSS<\/span> Cascading Style Sheets.<\/span><\/span><\/span> 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\u2019s default inline styles. Responsive layout values and `blockGap` are processed by the existing layout support and scoped with the block\u2019s generated container class.<\/p>\n\n\n\n
Configurable breakpoints<\/strong><\/h2>\n\n\n\n
WordPress provides two responsive style breakpoints by default:<\/p>\n\n\n\n
State<\/th>Media query<\/th><\/tr><\/thead>
@mobile<\/code><\/td>@media (width <= 480px)<\/code><\/td><\/tr>
@tablet<\/code><\/td>@media (480px < width <= 782px)<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
There is no @desktop<\/code> style key. The block\u2019s default style is the desktop\/base style and continues to apply at smaller sizes for any property that is not overridden.<\/p>\n\n\n\n
Themes can customize the breakpoint widths<\/a> with the new top-level settings.viewport<\/code> values:<\/p>\n\n\n\n
\"settings\": {\n\t\t\"viewport\": {\n\t\t\t\"mobile\": \"30rem\",\n\t\t\t\"tablet\": \"45rem\"\n\t\t}\n\t}<\/code><\/pre>\n\n\n\n
This produces the following ranges:<\/p>\n\n\n\n
@media (width <= 30rem) { \/* Mobile *\/ }\n@media (30rem < width <= 45rem) { \/* Tablet *\/ }<\/code><\/pre>\n\n\n\n
Breakpoint values must be non-negative numeric lengths using px<\/code>, em<\/code>, or rem<\/code>. CSS functions, percentages, unitless values, and other units are ignored.<\/p>\n\n\n\n
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.<\/p>\n\n\n\n
The configured viewport widths are used by responsive block styles and block visibility, and are previewable via the editor\u2019s device preview.<\/p>\n\n\n\n
settings.viewport<\/code> is a top-level setting. It cannot be configured separately for individual block types.<\/p>\n\n\n\n
Opting out of responsive editing<\/h2>\n\n\n\n
Sites that need to prevent users from making viewport-based styling changes can turn off responsive style editing<\/a> with the responsiveEditingEnabled<\/code> editor setting, which defaults to true<\/code>:<\/p>\n\n\n\n
function example_disable_responsive_editing( $settings ) {\n\t$settings['responsiveEditingEnabled'] = false;\n\treturn $settings;\n}\nadd_filter( 'block_editor_settings_all', 'example_disable_responsive_editing' );<\/code><\/pre>\n\n\n\n
When it is false<\/code>, both entry points for choosing a viewport are removed: the \u201cResponsive styles\u201d toggle in the Editor\u2019s View menu, and the \u201cViewport\u201d group in the \u201cStates\u201d dropdown in Global Styles. Device previews still work, and pseudo states such as Hover remain available.<\/p>\n\n\n\n
The setting governs the editing interface only. Responsive styles already saved in theme.json<\/code>, in Global Styles, or in a block\u2019s style<\/code> 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.<\/p>\n\n\n\n
Reviewed by @<\/span>tyxla<\/a>; props @<\/span>ramonopoly<\/a>, @<\/span>wildworks<\/a><\/p>\n
#<\/span>7-1<\/a>, #<\/span>dev-notes<\/a>, #<\/span>dev-notes-7-1<\/a><\/p>