WordPress 7.0 expands the Dimensions block 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. supports system with three significant improvements: width and height are now available as standard block supports under dimensions, and themes can now define dimension size presets to give users a consistent set of size options across their site.
Background
Previously, blocks that needed width or height controls implemented them as custom block attributes with their own editor UI User interface. This led to duplicated code, inconsistent experiences across blocks, and no straightforward way to define width or height values through Global Styles or theme.json. The broader Block API An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. goal is to handle these concerns uniformly through block supports, the same system that already covers spacing, typography, color, and more.
Width Block Support
PR: #71905
dimensions.width is now a first-class block support. Block authors can opt in by adding "width": true under the dimensions key in block.json:
{
"supports": {
"dimensions": {
"width": true
}
}
}Once opted in, the block gains a width input in the Dimensions panel of the block inspector and in the Styles panel of the Site Editor (under Styles > Blocks > Block Name). Theme authors can define default width values for specific block types via theme.json:
{
"styles": {
"blocks": {
"core/paragraph": {
"dimensions": {
"width": "300px"
}
}
}
}
}Block-level values set in the editor will override the theme defaults, following the same cascade as other block supports.
Themes can also disable the width control globally using the settings API:
{
"settings": {
"dimensions": {
"width": false
}
}
}The width support respects the full range of block support configuration options:
{
"supports": {
"dimensions": {
"width": true,
"__experimentalSkipSerialization": true,
"__experimentalDefaultControls": {
"width": false
}
}
}
}Height Block Support
PR: #71914
dimensions.height follows the same pattern as width. Block authors opt in via block.json:
{
"supports": {
"dimensions": {
"height": true
}
}
}Theme authors can set default height values per block in theme.json:
{
"styles": {
"blocks": {
"core/paragraph": {
"dimensions": {
"height": "300px"
}
}
}
}
}And the support can be disabled theme-wide:
{
"settings": {
"dimensions": {
"height": false
}
}
}Like the width support, height respects __experimentalSkipSerialization and __experimentalDefaultControls.
Dimension Size Presets
PR: #73811
Alongside the new width and height supports, themes can now define a set of named dimension size presets via theme.json. These presets appear in the width and height controls, giving users a consistent palette of sizes to choose from rather than requiring manual entry of values each time.
Define presets under settings.dimensions.dimensionSizes:
{
"settings": {
"dimensions": {
"dimensionSizes": [
{
"name": "Small",
"slug": "small",
"size": "240px"
},
{
"name": "Medium",
"slug": "medium",
"size": "480px"
},
{
"name": "Large",
"slug": "large",
"size": "720px"
}
]
}
}
}Each preset requires three fields:
| Field | Description |
|---|---|
name |
Human-readable label shown in the UI |
slug |
Machine-readable identifier (used to generate a CSS Cascading Style Sheets. custom property) |
size |
Any valid CSS length value (px, %, em, rem, vw, vh, etc.) |
The presets generate CSS custom properties following the --wp--preset--dimension-size--{slug} naming convention, consistent with other theme.json presets.
Control rendering: The number of presets defined affects how the control is rendered:
- Fewer than 8 presets: A slider control is shown, allowing users to step through the preset values.
- 8 or more presets: A select list (dropdown) is shown instead to keep the UI manageable.
In both cases, users can still enter a custom value directly.
Backwards Compatibility
These are additive changes. No existing blocks are broken. Blocks that do not opt in to dimensions.width or dimensions.height in their block.json are unaffected.
Blocks that currently implement custom width or height controls as attributes are encouraged to evaluate migrating to the new block supports, but this is not required in WordPress 7.0.
The dimensionSizes preset key is new; themes without it simply have no presets defined, which is the default behavior — users can still enter free-form values in the width and height controls.
Summary
| Feature | block.json key |
theme.json settings key |
theme.json styles key |
|---|---|---|---|
| Width block support | supports.dimensions.width |
settings.dimensions.width |
styles.blocks.{name}.dimensions.width |
| Height block support | supports.dimensions.height |
settings.dimensions.height |
styles.blocks.{name}.dimensions.height |
| Dimension size presets | — | settings.dimensions.dimensionSizes |
— |
Further Reading
Props to @aaronrobertshaw and @ryanwelcher for the width and height block support implementations, @aaronrobertshaw for dimension presets, and @andrewserong and @ramonopoly for technical review and proofreading.
Leave a Reply