Using The New Constrained Layout In WordPress Block Themes

One of the main goals of the WordPress Site Editor (and, yes, that is now the “official” name) is to move basic block styling from CSS to structured JSON.

GD

Ganesh DahalCSS-Tricks

·November 30, 2022·Articles

Using The New Constrained Layout In WordPress Block Themes

WordPress 6.1 continues the push to move core block styling from CSS into structured JSON within theme.json. Earlier default themes like Twenty Twenty-Two relied on workarounds in style.css for margins, padding, and interaction states. The latest release addresses the spacing problem directly, introducing more robust ways to define and control layout containers at both the theme and block level.

Root-level padding in `theme.json`

The ability to set padding directly on the <body> element has existed since the Gutenberg plugin’s experimental phase. This is defined under styles.spacing, where you can specify margin and padding values for the top, right, bottom, and left edges of the body:

{
  "version": 2,
  "styles": {
    "spacing": {
      "margin": {
        "top": "60px",
        "right": "30px",
        "bottom": "60px",
        "left": "30px"
      },
      "padding": {
        "top": "30px",
        "right": "30px",
        "bottom": "30px",
        "left": "30px"
      }
    }
  }
}

The resulting CSS is applied globally, giving all content consistent spacing by default:

body {
  margin-top: 60px;
  margin-right: 30px;
  margin-bottom: 60px;
  margin-left: 30px;
  padding-top: 30px;
  padding-right: 30px;
  padding-bottom: 30px;
  padding-left: 30px;
}

The limitation of root-level padding is that it applies to everything equally. Blocks that were intended to break out of that container—such as a full-width image—had no clean way to do so. WordPress 6.1 addresses this with padding-aware alignments and constrained layouts.

Opting into padding-aware alignments

Padding-aware alignments are an opt-in feature controlled by the useRootPaddingAwareAlignments property in theme.json. Introduced in Gutenberg v13.8, this property is false by default, so themes must explicitly enable it. When active, WordPress generates custom properties on the front-end <body> element and on the .editor-styles-wrapper class in the editor so spacing renders consistently in both contexts.

{
  "version": 2,
  "settings": {
    "appearanceTools": true,
    "useRootPaddingAwareAlignments": true,
    // etc.
  },

Enabling this feature also relies on appearanceTools being set to true, which activates UI controls for borders, link colors, typography, and spacing—including margin and padding—without requiring separate flags for each.

The custom properties generated by this setting are visible in DevTools on the front end:

In addition to the padding values, useRootPaddingAwareAlignments assigns left and right padding to any block supporting content or wide width values. Those widths can be declared in theme.json:

{
  "version": 2,
  "settings": {
    "layout": {
      "contentSize": "640px",
      "wideSize": "1000px"
    }
  }
}

contentSize sets the default maximum width for blocks.
wideSize defines a wider layout option for blocks that support it.

These settings translate into CSS that constrains nested blocks:

/* The default content container */
.wp-container-[id] > * {
  max-width: 640px;
  margin-left: auto !important;
  margin-right: auto !important;
}

/* The wider content container */
.wp-container-[id] > .alignwide {
  max-width: 1000px;
}

Notably, enabling this feature also generates a full alignment class, providing three distinct container configurations: content width, wide width, and full width. This applies specifically to layout-sensitive blocks: Columns, Group, Post Content, and Query Loop.

Block-level layout controls

When selecting any of these layout-specific blocks in the editor, the settings panel now exposes layout options derived from settings.layout in theme.json or from Global Styles:

The “Inner blocks use content width” toggle is enabled by default. Disabling it removes the max-width constraint, letting nested blocks fill the container edge-to-edge. Keeping it on forces nested blocks to respect either contentSize or wideSize, with numeric inputs available for one-off overrides.

For nested blocks, individual controls allow selection between content width, wide width, or full width. When “Full width” is chosen, WordPress applies negative margins derived from the root-level padding custom properties to achieve the breakout effect:

The `.alignfull` class sets negative margins on a nested block to ensure it takes up the full viewport width without conflicting with the root-level padding settings.

Constrained layout type

Beyond per-block settings, WordPress 6.1 restructured the Flex and Flow layout types and introduced a constrained layout type. The new layout produces semantic class names for each configuration:

Semantic layout class	Layout type	Supported blocks
`.is-layout-flow`	Flow layout	Columns, Group, Post Content, and Query Loop.
`.is-layout-constrained`	Constrained layout	Columns, Group, Post Content, and Query Loop.
`.is-layout-flex`	Flex layout	Columns, Buttons, Social Icons

The three layout types differ only in the styles they output:

Flow layout: Adds vertical spacing between nested blocks in the margin-block direction, with left, right, or center alignment options.
Constrained layout: Identical to Flow but with width constraints on nested blocks based on contentSize and wideSize.
Flex layout: Unchanged from earlier versions. Uses CSS Flexbox, laying items horizontally in a row by default, with vertical stacking as an option. Spacing relies on the gap property.

Migrating themes and disabling default styles

Existing block themes should update theme.json to define a constrained layout and enable useRootPaddingAwareAlignments, matching the pattern used in recently released default themes:

{
  "version": 2,
  "settings": {
    "layout": {
      "type": "constrained", // replaces `"inherit": true`
      "type": "default", // replaces `"inherit": false`
    }
  }
}

Theme	Root-level padding	Constrained layout features
TT3	Source c ode	Source c ode, T empl at e s
ProWP	Source c ode	Source c ode, Templates
Triangulate	Source c ode	Source c ode, Templates
Oaknut	Source c ode	Source c ode, Templates
Loudness	Source code	Source c ode, Templates
Pixl	Source code	Source c ode, Templates
Block Canvas	Source c ode	Source c ode, Templates
Rainfall	Source c ode	Source code, Templates

The default layout styles ship enabled in Core. Themes that need full control can disable them via a snippet in functions.php:

// Remove layout styles.
add_theme_support( 'disable-layout-styles' );

Disabling layout styles removes all base styling for those layouts, meaning themes must supply their own rules for spacing, alignment, and other layout behaviors across templates.

WordPress 6.1’s spacing and layout improvements give theme developers structured JSON options for root padding, breakout alignments, and constrained content widths. The remaining work—such as sticky positioning, new inner-block wrapper classes, and footer alignment refinements—is already tracked for future releases in the Gutenberg project’s public issue list.

GD

Written by

Ganesh Dahal

CSS-Tricks

Ganesh is a passionate WordPress learner. When he finds time, he digs into the Internet and surfs WordPress core, WP Tavern, and GitHub for any updates on the … More about Ganesh ↬

All articles by Ganesh Dahal →