Grids documentation
Introduction
Grids is a layout builder for WordPress, entirely based on the new Block Editor, that’s now part of the platform.
Before its adoption in Core, WordPress has relied for more than a decade on what we now call the Classic Editor. The Classic Editor delivered a basic writing experience and, frankly, it always fell short at creating anything more than flowing text.
That’s how page builders were born: they were created out of necessity to fill a gap between visual mockups and the actual, finished website.
We’ve built one ourselves too! It’s called Brix, it’s still alive and well to this day, and has helped us creating beautiful themes and completing numerous client projects.
It has been an amazing journey, that enriched us on so many levels, and deeply taught us how to manage layouts in WordPress.
Yet, when the Block Editor was released, we felt like it was time to try and do something new. So, with the knowledge that we acquired through the development of Brix, we decided to take the leap of faith of creating something on top of the Block Editor, React, and all that jazz.
Meet Grids

We’ve released Grids on the WordPress plugins repository for a variety of reasons. We’d like to single out two of them:
- We wanted to create a tool that could work perfectly together with all the other plugins that are being developed and released for the Block Editor.
- We wanted to get some feedback out of our efforts of diving in this new world of opportunities made available within WordPress.
Point number 1 hides probably the primary reason as to why Grids came to be. No matter how well designed and developed, page builders always end up locking users in, and the more you use them, as a web agency, or as a final client, the harder it gets to potentially stop using them one day.
Grids only takes care of the page layout – sections, columns, margins, etc. – but consciously chooses to keep away from the actual page content.
One may think of this as a weak point, but we think it’s actually Grids’ biggest strength because it enables the plugin to look beyond its horizon, and fully unlock the power of having a vast ecosystem of plugins working in the same direction, on the same platform.
In this context, both end users and developers win.
A bleeding edge foundation
Grids leverages the power of CSS grid.
CSS grid still sounds like a new, relatively known concept, but if we reverse the arrow of time for a second, we will find out that it’s actually been out in the wild for a good while.
In the beginning there where tables, then it was the time of floats and then came Flex, which enabled a whole series of visual controls that simply weren’t possible before.

With CSS grid, we’re now in a place where support is good enough to be actually implemented on real websites. And, for a tool as flexible as Grids aims to be, this changes the rules of the game completely.
Grids is able to compose visually complex layouts with ease and with as little HTML and style as possible. More so, we feel that Grids is able to give us a sense of control over our design that no builder could ever do.
Choosing CSS grid isn’t about wanting to use the latest cool thing available, at all costs: it’s simply about choosing the best tool for the job.
Transparency
Education isn’t something you can finish.
– Isaac Asimov
The best thing that you can do right now is download Grids and give it a try.
It’s been regularly updated, and with the ever-growing amount of blocks made available from other plugins, chances are you won’t be bored at all exploring the possibilities that the Block Editor puts at your disposal.
Is Grids the definitive layout builder for WordPress? Oh, it would be so nice to say that about Grids, but we’re not that presumptuous. One thing is for sure, though: we’re working towards making it better and better, adding just about the right features, and making it as compatible and widespread as possible.
There will always be room for improvement. Just like the quote from good ol’ Isaac at the beginning of this chapter, a good product isn’t something you finish, either: you build it over time, with ideas, hard work and listening to your people.
Is Grids perfect? Of course not! But you can make it better by testing it, using it and, why not, suggesting new features yourself.
It’ll be great to have you on board for the ride!
Sections
A Section is a portion of the page that aims at being visually distinct from the rest of the content. Sections are usually top-level blocks that you add one after the other; the sequence of sections is what makes your page layout.
Each Section that you create is composed by several different Areas. In their most basic form, you can think of Areas as columns, which are nothing else than containers for content blocks.
When you add a Section to your page, you’ll need to select how many areas you want to display: to do that, you can select from one of the available presets.

Alternatively, you can decide to create your own grid structure, by clicking on the Grid Designer button. For more about the Grid Designer, see the relative section in this document.
After you’ve added the Section to the page, please note that its Areas are already filled with some dummy content that you can remove.
When a Section is currently selected in the Block Editor, you’ll be able to edit its properties by using the controls available in the sidebar on your right. Here are the properties that define a Section:
Section layout: if you have selected a Section that is composed by, 2 or 3 Areas, you can choose how big those Areas will be. By default, the Areas will be the same in width, which means that, if you’ve chosen a 2-Area layout, each one of them will be covering half of the total Section width. When selecting a different type of arrangement for the Section, the content you had previously added to your Areas will adapt to the new layout.
Here’s a complete list of Section layouts:
- 1 Area, full-width
- 2 Areas
- 50% in width each
- 33%-66% width
- 66%-33% width
- 25%-75% width
- 75%-25% width
- 3 Areas
- 33% in width each
- 25%-50%-25% width
- 25%-25%-50% width
- 50%-25%-25% width
Section settings:
- Make columns equally tall: if this setting is set to ON, all Areas belonging to the Section will be forced to have the same height; if the setting is OFF, the individual height of each Area will depend on its content.
- Dimensions: through this panel it is possible to alter the spacing properties of the Section. The spacing properties are different depending on the device you want to target: desktop computers, tablets, and mobile devices. Spacing properties can be altered either by selecting both the values and units.
- Height: defines the overall height of the Section. By default, when specifying a height for the current section, the CSS output will produce a
min-height
rule; if you instead choose to lock the height of the section, the CSS rule being applied will beheight
. - Margin: governs the margins of the Section.
- Padding: governs the paddings of the Section.
- Height: defines the overall height of the Section. By default, when specifying a height for the current section, the CSS output will produce a
- Background: from here you’ll be able to change the background for the Section. You can choose to either have a solid color as background element, or pick an image from the Media Library. As for the Dimensions settings, the Background settings are dependent on the device width you want to target

Gutters
When working with grid systems, the notion of gutter comes into play. The gutter of a grid is the horizontal space between different columns. For consistency reasons, this setting shouldn’t belong to one specific section: that would lead to potentially have distinct sections, one next to the other, with different spacing properties, leading to visual breaks in the page grid.
For this reason, Grids provides a global page-wide gutter setting.
Global settings such as the page gutter value are technically meta fields for the Post Type. For this reason, if you’re using Grids in a Custom Post Type you’ve created, make sure that said Post Type has support for custom-fields
.
In order to access this setting, click on the Grids icon in the upper right corner of the editing screen, and open its page settings panel. As with margins and paddings, the gutter control is also dependent on the device it’s being applied to.

Keep in mind that gutter values that are too large to be contained in the grid will almost surely lead to unwanted visual results, especially when using fluid units, such as percentages or vw
. The optimal choice for gutter units is to use pixels, instead.
Display
From the Display panel in the sidebar on your right, you will be able to select whether the Section should be/not be visible in the currently selected device width.

Areas
When an Area is currently selected in the Block Editor, you’ll be able to edit its properties by using the controls available in the sidebar on your right. Here are the properties that define an Area:
- Dimensions: through this panel it is possible to alter the spacing properties of the Area. The spacing properties are different depending on the device you want to target: desktop computers, tablets, and mobile devices. Spacing properties can be altered either using their slider controls that will work using pixels as unit, or triggering an Advanced mode, that will allow you to select both the value and the unit being used.
- Margin: governs the margins of the Area.
- Padding: governs the paddings of the Area.
- Background: from here you’ll be able to change the background for the Area. You can choose to either have a solid color as background element, or pick an image from the Media Library. As for the Dimensions settings, the Background settings are dependent on the device width you want to target.

In the toolbar that is displayed when an Area is currently selected in the Block Editor, there’s another setting that you can use to alter the display of the Area contents: when changing the Vertical alignment property, the content of the Area will be positioned differently at the top, center or bottom of the Area, depending on your choice.
Display
From the Display panel in the sidebar on your right, you will be able to select whether the Area should be/not be visible in the currently selected device width.
Sections can work one within the other, which means that you can create a Section, choose a particular Area arrangement, and then decide to create another Section as a child of a content Area.
Nesting Sections one within the other might not always be the optimal solution, as it may complicate the page structure too much: for simpler purposes, you might want to use the standard WordPress columns block, instead.
In such a complex situation, we thought it’d be convenient to have a way to quickly jump from an Area to the Section it belongs to, or viceversa. When either a Section or an Area is currently selected in the Block Editor, the sidebar on your right will display a Structure diagram, that replicates the current structure of the Section you’re working with. The diagram is interactive: click on the outermost rectangle, and the Section will be selected; click on one of the contained rectangles, and you’ll select a specific Area.
If you prefer an alternative way to navigate the page structure, you can also access the Block Navigation control in the Block Editor toolbar on the top of the editing screen.
Grid designer
The Grid Designer allows you to create exactly the grid structure you want withing the boundaries of a Section.
When opening the Grid Designer, you will see a blank canvas that’s composed by an underlying grid of 12 columns, by 6 rows. Hover the mouse over the grid, and drag around the grid to create content areas.

The content areas you design will be laid out exactly in the way you compose them in the Grid Designer, both backend and frontend.
After you’ve added an Area to the composition, you’ll be able to edit its boundaries by dragging its borders, or you can place it somewhere else on the grid by dragging it. Keep in mind that Areas can overlap each other: you’ll be able to control which one is on top, by tweaking the Stack order parameter in the Area editing panel, under the Display tab.
Whenever you add an Area to your composition, a reference to it will be displayed in a sidebar placed on the right of the Grid Designer interface. Use that sidebar to either remove Areas from the
After you’re done editing the grid, click on the “Insert in page” button, to consolidate the layout.
Editing a section
If you have composed a Section with the Grid Designer, you can select it and then activate its Edit mode, by clicking on the pencil icon in the block toolbar.
When in Edit mode, the Grid Designer interface will be shown again, allowing you to edit/delete the previously created Areas, or add new ones to the composition.
Known issues
There are a few known issues that currently affect the plugin. The Block Editor is still in development, and some areas of it are still kind of wobbly. This also affects all the plugins, like Grids, that rely on it to work. In this page, which we will update as regularly as possible, we’d like to single out the issues that we or our users have been able to identify.
- Editing a reusable Section: when saving a Section as a reusable block, it was no longer possible to interact with the block insertion button within the Areas contained in the Section (GitHub ref: #16427). A temporary workaround for this was to edit the reusable Section in the reusable blocks editing screen. This issue should now be fixed in Grids version 1.2.18.