Block Editor: Understanding BlockGap

Written by Tinjure WP Posted on

Note: This post is part of understanding new features in full site editing (FSE) interface. This learning post is still in active development and updated regularly.

Block Editor BlockGap (also known as spacing) adds “the gap blocks using margins (top margins) because there’s no “gap” support in regular divs (no flex or grid)”.

In the Full Site Editing, Carolina describes BlockGap:

The blockGap setting in theme.json sets the vertical spacing between blocks by adjusting the margins depending on the position of the block:

  • The first block on the webpage and the first inner block or child block have no top or bottom margin.
  • The following blocks have a top margin that corresponds to the value in the theme.json setting, and no bottom margin.

Block Gap was initially introduced in Gutenberg 11.4 for spacing control in column blocks to handle gaps between the items, as shown in this video link. However, this created a problem.

Why it is Important?

Recently, I was trying to add a featured image cover block at the top in a single post template with background, it creates an annoying gap at the top (see below).

Screenshot showing to gap.

I spent almost an entire day trying to eliminate the top gap, but in vain. Therefore, I decided to dig in deeper in GitHub discussion threads and understand how this problem is solved.

BlockGap creates problem handling top and bottom block margin, as discussed in detail in this GitHub PR #37344. This is especially true, when we want to stack colored layout blocks (Group, Column) on top of each other while creating a theme.

In this GitHub PR, discusses stacking colored layout blocks on the top of each other without creating gap as demonstrated in this sort video.

Other related discussions on blockGap feature is available following the GitHub PRs listed under Resource section.

Using BlockGap in theme.json

In theme.json blockGap can be enabled with its value set to true under “settings“.

{
	"version": 2,
    ...
    ...
	"settings": {
		"spacing": {
			"blockGap": true
		}
	}
   ...
   ...
}

However, if the appearanceTools in the settings is set to true, then blockGap is also set to true and don’t require setting blockGap separately.

By default, blockGap value is set to false or disabled by default. It’s an opt-in property, just like other appearanceTolls items.

Default blockGap Value

In the theme.json the default blockGap value is set under the styles section as shown below:

{
	"version": 2,
    ...
    ...
	"styles": {
		"spacing": {
			"blockGap": "1.5rem"
		}
	}
    ...
    ...
}

Here is an example from Twenty Twenty-Two theme, where blockGap default value is set to 1.5rem.

Learning from Others

With this background, I started digging other block themes like Frost, pendant, archeo and others to understand how this problem was solved in those themes. In my local test site, I was using the latest versions of the WordPress 6.1 and Gutenberg 13.0, and the blockGap PR was already merged in the core.

After experimenting these themes and comparing with mine for sometimes, I realized that indeed my bug was related with my template structure, rather than the proper use of blockGap feature in my block theme.

Screenshot showing cover image without the gap.

As shown in the following code snippets, the header-single-cover pattern (line 3) was called before the “main” group which created the gap.

<!-- wp:template-part {"slug":"header-small-dark","tagName":"header"} /-->

<!-- wp:pattern {"slug":"khesara/header-single-cover"} /-->

    <!-- wp:group {"tagName":"main","style":{"spacing":{"margin":{"top":"0"},"padding":{"bottom":"80px"}}},"className":"site-content"} -->
    <main class="wp-block-group site-content" style="margin-top:0;padding-bottom:80px">
      
     ...
     ...

But when the header-single-cover pattern was called after the “main” group (line: 6), the top margin was eliminated because of the “margin-top: 0px” inline value of the “main” group.

<!-- wp:template-part {"slug":"header-small-dark","tagName":"header"} /-->

    <!-- wp:group {"tagName":"main","style":{"spacing":{"margin":{"top":"0"},"padding":{"bottom":"80px"}}},"className":"site-content"} -->
    <main class="wp-block-group site-content" style="margin-top:0;padding-bottom:80px">
      
  <!-- wp:pattern {"slug":"khesara/header-single-cover"} /-->
 ....
 ....
Wrapping Up

In this short learning-note post, discussion on blockGap features and how it can be used to eliminate top- and bottom- margins in templates was explored.

Resources

Before starting to create my own block patterns, I did a brief google search for useful guide and tutorials on creating patterns and found the following useful for my project.