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?
- Controlling available units
- Padding and margin controls
- Adding padding and margin
- Understanding block gap
- Controlling block gap
- Closing
What are the the dimension settings?
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.
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.
When you click on the unit selector, a list of available units will pop up.
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.
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:
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.
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.
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.
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.