Adding Margin and Padding to Blocks

The ability to control the margin, padding and block gap settings of blocks is one of the key features of full-site editing.

But it’s also a quite complex feature:

  • Blocks have default margins added through block spacing or block gap.
  • The theme.json file allows margins and padding to be added to blocks.
  • Blocks can have a dimensions panel to allow users to control margin and padding on a per block bases.

In this article we’ll have a look at how these elements all work together to control block margins and block padding.

The code snippets in this article use the theme.json file.

If you’re not familiar with how to use theme.json to configure a theme, you can take the free Theme.json Explained course.

Table of Contents

What are the the dimension settings?

A screenshot of the block editor with the Dimensions panel.

The dimensions panel displays an interface that allows users to control the spacing around blocks. When we talk about spacing, we mean of course margin and padding. But Full-Site Editing also includes a specific feature called block spacing, or block gap.

The default is not to show all settings. There is a button that allows you to enable additional controls.

A screenshot of the default Dimensions panel.
The button with the three dots opens the menu with all available settings.
A screenshot of all available Dimension settings.
Clicking on a setting enables it.

Controlling available units

Each control in the dimensions interface is made up of two elements. There is the field to enter a number, and there is the unit selector.

A screenshot of yhe unit selector of the Padding control.
The unit selector of the Padding control.

When you click on the unit selector, a list of available units will pop up.

A screenshot of the unit selector in the dimension panel.
The list of available units as set in theme.json.

The available units can be controlled through the units entry in theme.json:

"spacing": {
    "units": [
        "%",
        "px",
        "em",
        "rem",
        "vh",
        "vw"
    ]
}Code language: JavaScript (javascript)

Padding and margin controls

The controls to set margins and padding work the same. The default interface allows you to enter a number for all four sides of a block. But there is also a selector that allows you to set values for individual sides.

A screenshot of the button that allows the padding controls to be unlinked.
The Unlink Sides button in the Dimensions panel.
A screenshot of the padding controls for each of the four sides of a block.
With the sides unlinked, you can add individual values for each side.

These controls allow you to override the default margin and padding for individual blocks. While you can still use CSS to control these properties, using the theme.json file is a much better option.

Adding padding and margin

The spacing around blocks can be controlled through the styles section of theme.json. If you are familiar with CSS, you’ll have no trouble understand the structure of these instructions. Since these styles are per block, you need to use a block selector.

This is an example of a complete theme.json file that adds padding to the top of the post title block:

{
    "version": 2,
    "styles": {
        "core/post-title": {
            "spacing": {
                "padding": {
                    "top": "30px"
                }
            }
        }
    }
}Code language: JSON / JSON with Comments (json)

If you wanted to set the same margin for all four corners of a block, this is what the spacing instruction would look like:

"spacing": {
    "margin": "30px"
}Code language: JavaScript (javascript)

Understanding block gap

A lot of developers are confused about the block gap or block spacing feature. This is because the feature wasn’t very well explained when it was added.

A WordPress install can have blocks from different sources. A theme will usually provide styles for blocks in WordPress Core. But blocks from plugins for example don’t get specific styles.

But still if you add any block to a blog post, or full-site editing template, it should integrate seamlessly. And a main aspect of that is the space surrounding the block.

What the block spacing feature does is add a margin before every single block except:

  • The first block on a webpage using a block theme (so inside of .wp-site-blocks).
  • The first block inside of a container (for example a group block).

This may sound confusing, so let’s look at an example. Let’s take a block template with these contents:

A screenshot of an outline of the blocks of a demo block template.
The outline of our demo template.

Let’s look at how spacing is added to these blocks.

The group block is the first block of this template, so there’s no space between this block and the top of the page.

A screenshot of a first block in a block template container with no block gap applied to it.
The first block of a block template does not have block gap spacing applied.

This is the CSS that WordPress generates for this first block on the page:

.wp-site-blocks > * {
    margin-block-start: 0;
    margin-block-end: 0;
}Code language: CSS (css)

If we move on to the first paragraph block, it also does not have space at the top. This is because it’s the first block inside of the group, which is a container.

A screenshot of a first block in a container with no block gap applied to it.
The first block insider of a container does not have block gap spacing applied.

As you can see the CSS is generated specifically for this particular group block:

.wp-container-1 > * {
    margin-block-start: 0;
    margin-block-end: 0;
}Code language: CSS (css)

But now if we look at the image block, we see it has a space towards the top of the block.

A screenshot of a block with the block gap applied to it.
The second and any other blocks in a container have a top margin applied through block gap.

As the image is the second block of the container, the following block gap styles are applied:

.wp-container-1 > * + * {
    margin-block-start: var( --wp--style--block-gap );
    margin-block-end: 0;
}Code language: CSS (css)

As you can see from the selector, any other block after the image will also be targeted by this instruction.

Controlling block gap

The global block spacing can be controlled through theme.json. The blockGap setting is part of the styles section:

"styles": {
    "spacing": {
        "blockGap": "1.5rem"
    }
}Code language: JavaScript (javascript)

Or if you don’t like the feature, you can turn it off using the settings section:

"settings": {
    "spacing": {
        "blockGap": false
    }
}Code language: JavaScript (javascript)

Closing

There you have it! All you need to know about margin, padding, and block gap settings in the block editor.

The ability to managed these settings is just one of the many features that you can configure with theme.json. There are detailed guides for the color settings and typography settings available.

If you aren’t yet confident in working with theme.json, my free Theme.json Explained course is the way to go.

Level Up Your WordPress Business With One Email Per Week

Every Sunday, I send out tips, strategies, and case studies designed to help agencies and freelancers succeed with modern WordPress.

My goal is to go off the beaten path, and focus on sharing lessons learned from what I know best: building websites for clients.

100% free and 100% useful.

Feel free to check out the latest editions.