Custom Block Margin

Last modified: March 5, 2025

link Extension name

t2/custom-block-margin

link Setting version

You need to set a version in t2.json. This is used to determine which version
of the extension to use.

If you don't set a version, the extension will trigger a warning and fallback to
version 1. Latest (and recommended) version is 3.

{
	"t2/custom-block-margin": {
		"version": 3
	}
}

link v3

This version will override Block Spacing API for all containers with inner blocks in flow layout, including Post Content/root blocks, Group, Column, Media and Text, Cover, T2 Accordion, T2 Factbox, T2 Infobox, T2 Simple Media and Text, T2 Tabs etc. and enforce the same block spacing rules everywhere. (All current containers). Out of the box this extension uses the default spacing scale in WordPress.

link Extending

If you are using a different spacing scale for your project, or want to change any other part of the setup, you can use the built in filters:

t2/custom_block_margin/v3/gaps
t2/custom_block_margin/v3/default_gap
t2/custom_block_margin/v3/last_gap
t2/custom_block_margin/v3/last_selectors
t2/custom_block_margin/v3/containers

link Setting new spacing sizes

To change spacing sizes for a project first change the spacing sizes in theme.json (settings.spacing.spacingSizes). We recommend using the default spacing scale (20-80) for consistency, using 50 as medium reference point for gap between two paragraph blocks. If you need to add additional spacing sizes, add to the top (90) or bottom (10).

link Example: Changing spacing scale to only `normal` and `small` in `theme.json`.

{
	"settings": {
	"spacing": {
		"defaultSpacingSizes": false,
		"spacingSizes": [
		{
			"slug": "small",
			"name": "Small",
			"size": "1rem",
		},
		{
			"slug": "normal",
			"name": "Normal",
			"size": "2rem",
		},
		]
	}
	}
}

Then updated Custom Block Margin setup correspondingly with the same gaps and update the default and last gaps.

\add_filter( 't2/custom_block_margin/v3/gaps', function ( array $gaps ): array {
  return [
    'none' => [
      ...$gaps['none'],
    ],
    'small' => [
      ...$gaps['50'],
    ],
    'normal' => [],
  ];
} );

\add_filter( 't2/custom_block_margin/v3/default_gap', fn() => 'normal' );
\add_filter( 't2/custom_block_margin/v3/last_gap', fn() => 'normal' );

link For reference, this is the current default spacing scale in WordPress:

Key	Value	Alias
`–wp–preset–spacing–20`	0.44rem	2X-Small
`–wp–preset–spacing–30`	0.67rem	X-Small
`–wp–preset–spacing–40`	1rem	Small
`–wp–preset–spacing–50`	1.5rem	Medium
`–wp–preset–spacing–60`	2.25rem	Large
`–wp–preset–spacing–70`	3.38rem	X-Large
`–wp–preset–spacing–80`	5.06rem	2X-Large

link Add/remove block containers:

Use the t2/custom_block_margin/v3/containers filter to add or remove supported containers. (All current containers)

\add_filter( 't2/custom_block_margin/v3/containers', function ( array $containers ): array {
  return [
    ...$containers,
    '.some-additional-container',
  ];
} );

link Legacy versions

link v2

Changing the margins can be done trough theme.json in your theme with the following structure:

{
	"settings": {
		"custom": {
			"t2/custom-block-margin": {
				"spacing": {
					"default": "3rem",
					"last": "5rem",
					"xSmall": "0.5rem",
					"small": "1rem",
					"medium": "3rem",
					"large": "5rem",
					"xLarge": "10rem"
				}
			}
		}
	}
	...
}

link v1

Add basic style margin between blocks on the site. The config allows you to set
3 different margins.

normal: Default block margin.
small: Margin used on blocks that needs less space between them. Ex. two paragraphs after each other.
last: Last block in block context container (except full width blocks).

{
	"settings": {
		"custom": {
			"t2/custom-block-margin": {
				"spacing": {
					"normal": "3rem",
					"small": "1rem",
					"last": "5rem"
				}
			}
		}
	}
	...
}