T2 Extended Layout Support

As the name suggests, the Extended Layout Support extends the native WordPress
layout types (flow, constrained, flex and grid) with some additional features.
This support doesn't replace or add new layout types, it just enhances the
existing ones.

link Reason why

The purpose of the T2 Extended Layout Support is to overcome some of the limitations
of the native WordPress layout and align supports:

• Support for predefined theme-wide and block-specific widths beyond content, wide and full widths.
• Support for predefined theme-wide and block-specific heights.
• Add layout support to WordPress and third-party blocks in theme.json.
• Define theme-wide layout settings for blocks in theme.json.
• Override block settings in theme.json.
• Override theme settings for individual blocks in theme.json.
• Granular control over the author user interface.
• Granular control over the options exposed to the author.
• Define block-specific default values in theme.json.
• Bundle layout controls in the sidebar.

In short, the T2 Extended Layout Support moves control from block
developers to theme developers by allowing them to configure block
layout controls and behavior in theme.json.

link Some questions you might have

link Why not just use the WordPress core layout support?

Well, let me start by asking you a question: When was the last time you
created a block with core layout support?

I've been three years at Dekode at the time of writing, and I've hardly seen a
handful. So, the next question is: Why is that? Because it adds all kinds of controls
to your blocks which you simply don't need, and it's not trivial (or possible) to
remove or configure them.

That said, the WordPress core layout support is great, except for the
author user interface and the limitations mentioned above.
If used more often, we stay closer to the core and save ourselves a lot of work.

The objective of the T2 Extended Layout Support is to overcome the limitations
of the core layout support and make it easier for developers and authors to use it.

link Why custom controls?

The T2 Extended Layout Support doesn't change the core WordPress layout or
align support. However, it does replace the core layout controls with its own.

Like it or not, this is necessary in order to provide granular control over
the author user interface. In theme.json, you can only turn some of the
core layout controls on and off, but not all, and you can't control their options.
Have you ever tried to hide one of the horizontal or vertical alignment options?

The result of this limitation is that authors are sometimes confronted with
a confusing user interface with an overwhelming number of controls and options,
some of them having no effect on the layout at all. Or, more often, we simply
don't use the core layout support and blocks (i.e. core/group) even of we should,
and invent the wheel one more time in custom blocks.

On a personal note, I think the core layout and align controls are confusing
and spread all over the WordPress editor. Also, it's not always obvious if they
control the block itself, or it's content. Bundling these controls into one or two
sidebar panels reduces complexity.

link Additional container widths

The most important feature is extending the native container widths from
only content, wide and full to supporting any number of container widths
in your project. You can define container widths for (outer) block widths
and for (inner) block content widths.

In contrast to the native layout types, the container widths are applied
as classes and css variables, which allows you to override the
user settings if necessary, i.e. for mobile.

link Example: Container width project or block settings

theme.json

{
  "t2/layout": {
    "maxBlockWidth": {
      "xs": "35rem",
      "sm": "var(--wp--style--global--content-size, 50rem)",
      "md": "60rem",
      "lg": "var(--wp--style--global--wide-size, 75rem)",
      "hg": "85rem",
      "full": "none"
    },
    "maxContentWidth": {
      "xs": "35rem",
      "sm": "var(--wp--style--global--content-size, 50rem)",
      "md": "60rem",
      "lg": "var(--wp--style--global--wide-size, 75rem)",
      "hg": "85rem",
      "full": "none"
    }
  }
}

link Minimum content height

In addition to the max block and content width, the Extended Layout Support
also lets you add any number of minimum content heights to your project.

In contrast to the native minimum height support, the extended minimum height
support use classes and css variables, which allows you to override
the user settings if necessary, i.e. for mobile.

link Example: Minimum container height project or block settings

theme.json

{
  "t2/layout": {
    "minContainerHeight": {
      "xs": "10rem",
      "sm": "20rem",
      "md": "30rem",
      "lg": "40rem",
      "hg": "50rem",
      "full": "100vh"
    }
  }
}

link Activating Extended Layout Support

The Extended Layout Support is completely deactivated by default. It is
activated in theme.json only, not by adding support to any block.

The Extended Layout Support is a collection of features, which you can
enable or disable separately for a website and individual block.
For each individual block, you should only enable the features that are helpful
for content authors.

In order to activate Extended Layout Support, you must

1. Activate Extended Layout Support for your website in theme.json, and
2. Activate Extended Layout Support for each individual block, also in theme.json.

Technically, you can activate the Extended Layout Support for all blocks,
even core and third-party blocks. They don't have to have native support for
the Extended Layout Support, you can still activate support for them in theme.json.

That said, there are probably only a limited number of blocks where the
Extended Layout Support is helpful. Consider activating it for

1. Blocks with container widths (maxBlockWidth only)
2. Blocks with inner blocks.

link Example 1: Activate Extended Layout Support for a website: default settings

This will activate the Extended Layout Support for a website with default
settings.

theme.json

{
  "settings": {
    "custom": {
      "t2/layout": true
    }
  }
}

link Example 2: Activate Extended Layout Support for a website: custom settings

This will activate the Extended Layout Support for a website with custom
settings.

theme.json

{
  "settings": {
    "custom": {
      "t2/layout": {
        "maxBlockWidth": {
          "xs": "var(--wp--style--global--content-size)",
          "sm": "50rem",
          "md": "61.25rem",
          "lg": "var(--wp--style--global--wide-size)",
          "hg": "82.5rem",
          "full": "none"
        },
        "boxSizing": true,
        "maxContentWidth": {
          "xs": "var(--wp--style--global--content-size)",
          "sm": "50rem",
          "md": "61.25rem",
          "lg": "var(--wp--style--global--wide-size)",
          "hg": "82.5rem",
          "full": "none"
        },
        "minContainerHeight": {
          "sm": "10rem",
          "md": "20rem",
          "lg": "30rem",
          "hg": "40rem",
          "xh": "48rem",
          "full": "100vh"
        },
        "horContentAlign": true,
        "verContentAlign": true,
        "horMobileAlign": true
      }
    }
  }
}

link Example 3: Activate Extended Layout Support for a block: website settings

This will activate the Extended Layout Support for a block with the website settings.

theme.json

{
  "settings": {
    "blocks": {
      "<block-name>": {
        "custom": {
          "t2/layout": true
        }
      }
    }
  }
}

link Example 4: Activate Extended Layout Support for a block: custom settings

This will activate the Extended Layout Support for a block based on the
default website settings, but with custom settings for this specific block.

theme.json

{
  "settings": {
    "blocks": {
      "<block-name>": {
        "custom": {
          "t2/layout": {
            "contentLayout": false,
            "minContainerHeight": {
              "sm": "15rem",
              "md": "25rem",
              "lg": "35rem"
            },
            "maxContentWidth": false
          }
        }
      }
    }
  }
}

link Available feature settings