Understanding blockGap in WordPress Block Themes

What is blockGap?

In WordPress, blockGap refers to the space or distance between blocks in the Gutenberg block editor. It allows you to modify the vertical (and in some blocks horizontal) spacing between blocks to provide greater design control.

Horizontal block gap can be used between inner blocks such as in rows, buttons and social icons. 

In the editor, the control for blockGap is called Block Spacing, located in the Dimensions panel.

By default, each block has pre-set spacing, creating a separation between different elements. However, there may be instances where you need to customise the gap between blocks to achieve a specific design or layout.

If blockGap has been enabled in theme.json, you can adjust it by accessing the block settings in the editor. This allows you to increase or decrease the space between blocks by choosing a predefined value or manually inputting a custom measurement.

Tailoring the Block Gap contributes to enhancing readability, establishing a clearer visual hierarchy, and improving the overall user experience of your WordPress website.

How to enable blockGap

blockGap can be enabled within the settings.spacing object in theme.json. This enables the block spacing setting in the editor for each block that supports it.

This is how you can enable it in theme.json:

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

If you have already enabled appearanceTools in the settings section of theme.json, you do not technically need to enable blockGap again. However, it’s fairly common to add it anyway just for clarity’s sake.

By default, block gap support is disabled (null), but you can enable it in your theme.json in two different ways:

1. Set blockGap to true, to enable the block gap styles support and editor control, so users can tweak the block gap per block in the editor.

2. Set blockGap to false, to enable the block gap styles support but hide the block gap control in the settings sidebar for each block. This is useful if you as the developer want to be able to define block spacing sizes in theme.json but don’t want users to be able to edit it in the editor.

If you set blockGap to null, the block gap styles support and editor control will not be enabled.

How to add a default site-wide blockGap

You can set a site-wide blockGap inside the styles section in theme.json, like so:

{
  "styles": {
    "spacing": {
      "blockGap": "1.5rem"
    }
  }
}

This ensures that all blocks have some separation by default.

How to add a default block-specific blockGap

You can set a block-specific value for blockGap inside the styles section in theme.json, like so:

{
  "styles": {
    "blocks": {
      "core/buttons": {
        "spacing": {
          "blockGap": "1rem"
        }
      }
    }
  }
}

This will give all buttons horizontal spacing of 1rem.

Using spacing presets for blockGap

The padding, margin and blockGap controls can utilise spacing presets defined in theme.json. This allows users to slide between preset values to change the spacing amount.

You can define custom spacing sizes within the settings.spacing.spacingSizes array of theme.json, like this:

{
  "styles": {
    "spacing": {
      "blockGap": "1.5rem"
      "spacingSizes": [
   	{
   	  "name": "Small",
   	  "slug": "sm",
   	  "size": "clamp(1.5rem, 3.5vw, 2rem)"
   	},
        {
   	  "name": "Medium",
   	  "slug": "md",
   	  "size": "clamp(2rem, 5vw, 3rem)"
   	},
   	{
   	  "name": "Large",
   	  "slug": "lg",
   	  "size": "clamp(3rem, 7.5vw, 5.5rem)"
   	}
      ]
    }
  }
}

You can only have a maximum of 7 preset spacing sizes. If you don’t set any custom spacing sizes and blockGap is enabled, WordPress will use its default spacing scale.

WordPress default spacing scale

If you don’t set custom preset spacing values, WordPress has its own default spacing scale that will be used for blockGap.

There are seven steps in the default spacing scale and each step multiplies the value by 1.5.

Each of the 7 default steps are assigned to a CSS custom property:

How to add your own custom spacing scale

If you want to add your own custom spacing scale instead of custom preset values, you can use the settings.spacing.spacingScale property in theme.json:

{
  "version": 2,
  "settings": {
    "spacing": {
      "spacingScale": {
        "operator": "*",
        "increment": 1.6,
        "steps": 7,
        "mediumStep": 1.6,
        "unit": "rem"
      }
    }
  }
}

This guide on using blockGap in WordPress Block Theme development should equip you with the knowledge needed to space out your blocks like a pro.

Understand that there is no right or wrong way to define blockGap. Both spacingSizes and spacingScale are totally acceptable ways to define the distance between blocks. It all depends on your preference and design system.

Happy coding 🙂