Getting your theme ready for Gutenberg

In a few months, WordPress 5.0 will be released with a new editor, code-named Gutenberg. It will be a huge improvement for content editing, but it will require some work to ensure your theme takes full advantage of the new features.

Here’s an introduction to Gutenberg I put together for our local WordPress meetup.

If you’re building custom themes for clients, you should be adding Gutenberg support right now. You might not activate it for your client, but you should be testing your theme with Gutenberg.

We have even built a few sites that already use Gutenberg as the editor:

Here are some quick tips to help you make the most of Gutenberg.

Frontend Styles

You likely have styles for many of these items (blockquotes, horizontal rules), but Gutenberg loads its own styles. You may need additional styles and specificity to ensure consistency.

Turn on wide images

Users can now have “wide” and “full” image alignments if your theme supports it. This allows the image to expand beyond the wrapping content area. You can see an example on my About page.

To add support, simply include this in your theme’s functions.php file:

add_theme_support( 'align-wide' );

It’s up to the theme to style these alignments on the frontend to ensure it works well with the theme. Here’s the base styling I use:

@media only screen and (min-width: 768px) {
.alignfull {
margin-left: calc(50% - 50vw);
margin-right: calc(50% - 50vw);
width: auto;
max-width: 1000%;
.alignwide {
margin-left: calc(25% - 25vw);
margin-right: calc(25% - 25vw);
width: auto;
max-width: 1000%;
.alignwide img,
.alignfull img {
display: block;
margin: 0 auto;
view raw style.css hosted with ❤ by GitHub


Gutenberg includes two types of blockquote blocks: a standard blockquote and “large” one. It also includes a “pull quote” blockquote which is designed to be smaller and floated in the content.

All quotes can include a citation, using the <cite> element. I use Better Blockquotes to add this to the current WordPress editor.

Here’s some base styling I use for these elements (using SASS):

blockquote {
background: transparent;
margin: 0 0 $base-margin;
@include font-sizes( 18px, 19px, 22px );
font-style: italic;
padding: 0;
text-align: center;
cite {
display: block;
font-size: 18px;
margin-top: 17px;
p:last-of-type {
margin-bottom: 0;
&.is-large.wp-block-quote {
@include font-sizes( 22px, 26px, 32px );
margin: 0 0 $base-margin;
padding: 0;
cite {
text-align: center;
&.wp-block-pullquote {
border-top: 2px solid $base-color;
border-bottom: 2px solid $base-color;
padding: $base-margin 0;
view raw _style-guide.scss hosted with ❤ by GitHub

Horizontal Rules

There’s a horizontal rule with its own class ( hr.wp-block-separator), so you should make that match your theme’s standard horizontal rule.


Gutenberg has a button block with its own default styling applied. You’ll likely want to customize this to match your theme’s button styles.

I have a blocks partial for all my block-specific styles.

.wp-block-button {
margin-bottom: $base-margin;
text-align: center;
.wp-block-button__link {
@extend %button;
view raw _blocks.scss hosted with ❤ by GitHub
%button {
background: $highlight;
border: none;
border-radius: 4px;
box-shadow: none;
color: $white;
cursor: pointer;
padding: 10px;
text-align: center;
text-decoration: none;
width: auto;
-webkit-appearance: none;
&:hover {
background-color: darken( $highlight, 10%);
color: $white;
text-decoration: none;
view raw _placeholders.scss hosted with ❤ by GitHub

Backend Styles

You can enqueue your own styles & scripts in Gutenberg using the enqueue_block_editor_assets hook. This works the same as loading styles & scripts on the frontend using wp_enqueue_scripts.

Do not load your entire frontend stylesheet in Gutenberg. You should only load relevant styles, and prepend them all with the .edit-post-visual-editor class to ensure it only applies to the editor (not the WP backend menu, metaboxes…).

SASS comes in handy here. I break my main stylesheet into smaller partials, then generate a separate stylesheet for Gutenberg.

Here’s my main.scss file, which generates the main css file on the frontend. Here’s my gutenberg.scss file, which generates a CSS file for loading in Gutenberg.

  • I’m only including relevant styles from the main stylesheet (style-guide, post elements, and blocks)
  • I have a gutenberg partial for Gutenberg-specific styles – styles that shouldn’t appear on the frontend. I’m using this to “undo” certain styles Gutenberg adds to elements, so those elements match my frontend.
  • Everything is wrapped in .edit-post-visual-editor, limiting it to only the visual editor, and increasing specificity of my general styles so they overwrite Gutenberg ones.
  • I’m setting the max width of blocks to match the site’s max width on the frontend ($grid-max-width is defined in _base.scss)

Complex Templates

For modular templates that cannot be built with a single editor, I disable both Gutenberg and the classic editor, then build the editing screen with metaboxes. This ensures a seamless transition when Gutenberg is released.

In the future it may be possible to build these pages with Gutenberg, but it’s not stable enough now to attempt. Block building is still difficult, and core features are still changing.

In the next six months, I expect ACF (or a plugin like it) to pivot to block building, providing the tools for developers to easily create the blocks they need for custom theme development with minimal time and a unified design.

Is Gutenberg ready for clients?

After you optimize your theme for Gutenberg, you could leave the plugin active so the client can use it.  I’m not using Gutenberg with clients yet. It has come a long way and is fun to use, but the UI needs some work and there are many outstanding issues.

When we get closer to the WP5.0 release, I’ll setup Gutenberg on our staging environments so clients can experiment with the new editor without affecting the production site’s content.

A Good Start

Gutenberg is still changing. The styles we create now might not perfectly align with the final release of Gutenberg. But by starting with a good base and structuring your theme to work well with Gutenberg from the start, you’ll only need minor changes to get it perfect.

Your clients will appreciate the effort future-proof their site, and you’ll minimize the amount of work you’ll need to do once Gutenberg is released.

Any more tips?

Do you have any recommendations for making custom themes more Gutenberg-ready?


Receive New Posts by Email


  1. I was just beginning to look into what would be needed to convert to Gutenberg. So this was perfect timing. Thank you, Bill!

  2. Wow! I see a lot of work coming to make sure all my client sites can co-exist with Gutenburg. Thanks for the detailed start.

  3. I just received my first request from a client asking that I do some testing to ensure the custom theme we developed for them is WP 5.0 / Gutenberg compatible. This post will form the basis of our action plan to set up a testing and validation process.

    Many thanks for this Bill. Well done.

  4. Great read. Found this particularly funny given the circumstances…

    “Clients will appreciate the effort to future-proof their site”

    Future-proof, at least until the next time WordPress decides to make breaking changes. 😉

    1. You could use anything you like. It’s expected that the .alignwide class be some amount wider than the content area, and I picked half the distance between the left/right edge of the screen and the content area.

      For the .alignfull class, the left/right margin of calc( 50% - 50vw) makes it expand the full width of the screen. Technically, it adds negative left/right margin equal to the space between the left/right side of the screen and the content area.

      For the .alignwide, I cut this in half. calc( 25% - 25vw) makes the image take up half the gap between the left/right side of the screen and the content area.

  5. Hey Bill, thanks, this is great stuff. I’ve made heavy use of ACF Pro in a theme I’m currently developing, mainly for the “flexible content” fields. I know you’ve worked with ACF Pro in the past, so thought I would ask: Do you know if Gutenberg “blocks” will allow me to completely move away from a plugin like ACF, giving me the ability to add my own custom “blocks” to do what “flexible content” field allow me to do? If so, I would love to start transitioning completely away from using a plugin like ACF Pro or CMB2. Hoping this isn’t too specific a question for this post. Thanks!

    1. While it’s theoretically possible, it would likely require orders of magnitude more time to build (think 10-100x the time you spend with ACF). A better comparison would be building your own custom metabox with its flexible content field from scratch, except you’re doing it in JavaScript, a language with which you might not be as familiar.

      I think most developers will use ACF or a similar plugin to create custom blocks, in the same way you use ACF now to create custom metaboxes. For now, I’m still using custom metaboxes for complex pages like this and disabling Gutenberg just on those templates.

  6. Very helpful, thank you Bill.

    I’m looking forward to Gutenberg, but it’s a big change. Some flexibility of it might not be that desirable (like plugins like The Events Calendar Allowing to shift their structured content blocks to other places in each separate post instead of presenting a predictable user experience), but it is nice to have options for when it is needed.

    One thing I especially wonder is how it will work regarding responsiveness. I would imagine that at least all size- and visibility-related attributes of blocks and text may need different settings for different device-sizes. Page builders tend to have attributes to select on which devices (large, medium, small) each block is shown and at what size and themes deliver that in a structural way, but when the content editor allows that to be changed, without that kind of responsiveness options, than small devices may not get an optimal experience. I imagine that might still be developed , since it is an obvious requirement, but it is something I’m too looking for.

    Images is an obvious subject there, since testing tools advice on compressing images and using smaller file-sizes on smaller displays. I have found it to be an increasing complicated subject in the responsive era and standard themes often seem to just use larger images for all displays, like it seems this website does too. I wonder how having users grow and shrink images at will in a page/content builder like Gutenberg will impact image delivery and related source-code and if that will be a subject for WordPress core or theme-developers to solve.



    1. The blocks themselves come with their own styling to ensure they work well across all devices. For instance, a pull quote appears full width on mobile but floated to the left or right on tablet and desktop.

      Beyond the ability to add custom CSS classes to blocks, I don’t think there’s any plan for providing options to control the look at different break points. It’s up to the theme developer to style those blocks effectively.

      This is a good example of why page builder plugins are not going away. They’ll likely shift to providing users more options in the Gutenberg editor.

      To your question regarding images, this is why WordPress has built-in support for srcset. Users can insert an image, and along with it include a list of smaller images the browser can use if they are a better fit.

      As a theme developer, the best thing you can do is ensure all (or most) of your custom image sizes use the same aspect ratio so there’s multiple sizes in the srcset.

      1. Thanks for the reaction, Bill. I know of the srcset support of WordPress, but that only adds like your last sentence says images with the same aspect ratio to the srcset, and when the design isn’t based on that and the mobile view needs another ratio ( f.i. because on mobile a background-image of a cta or title would need more height on mobile phones) then one needs to fiddle still and the default srcset of wordpress isn’t enough.

        Plugins like Woocommerce also might decide to change the way they crop images (or in case of woo not allow to crop single product images) and change the rules again. But we have to cope.

        By the way there is discussion going on Gutenberg in GitHub about adding a wrapper block to insert responsiveness to the editor, so the community is actively thinking about this problem and might yet present an answer. To not do so, would decrease the usability of some options it provides. The wrapper block would helas mean responsiveness would be implemented by replicating all blocks for each breakpoint and use display:none to regulate which is shown, so it’s an easy coding solution, but not very elegant or lean.

        The solution of having the theme handle responsiveness might be challenged by the fact that Gutenberg allows to set font-sizes and such by the editor and adds a “style=…” attribute to the element to implement this. Since now that is inline styling (high priority) and users can change image-sizes and font-sizes at will, the theme can no longer easily control how everything is presented.

        That’s why page builders need to be quite complete in the options of each element to be usable. The builder basically replaces the theme’s functionality for the ui-element. I don’t know how all that inline styling will effect SEO, not to speak about duplicating lots of content when wrapper blocks are implemented for responsiveness, but Gutenberg will most likely move some control from the theme to the editor and in the end visions that visitors themselves will control how they want to see modules on their display, making unclear what roles themes will have (if any) in that future. It’s a step unto new territory. Exiting times.

        Page builders will probably decide whether to adopt the editor in their page building ways, or find a way to keep using their own version and interface. Since lots of them are front-end editors by now, it will probably be both if they want to keep using an admin-editor too.

        Given Gutenberg i would imagine that lots of new elements will be provided by others too, especially the plugins that now provide them by shortcodes, hopefully will shift to Gutenberg. But there are offcourse still many (see reviews of the Gutenberg plugin) that don’t like what Gutenberg is doing and want to keep just a non-WYSIWYG text-editor.

        We’ll see. Right now, I welcome Gutenberg and the vision of the drivers of it.

  7. Thanks for all your Gutenberg posts. I’m updating my starter theme in preparation and I’ve found your posts helpful.

    Two questions about the full-width alignment.

    In the back-end, Gutenberg seems to style the align-full to grow an image if it is too small. Using these align-full styles, images only grow up to their 100%. Gutenberg has it easy though because the back-end editor isn’t inside of a max-width box.

    Second, any solution I’ve found (regardless of over-scaling the images or not) results in a horizontal scrollbar because vw includes the vertical scrollbar if present. It’s not present in demos that don’t induce the scrollbar. You can do things like calc( 100vw – 17px ) to accommodate it, but it’s not even constant and will be less than full-width if there doesn’t happen to be a scrollbar.

    Have you come across that? I almost always do a max-width container for all the page content, but this makes me wonder if instead the descendants of the main content area should get the max-width instead (except for full-width ones, of course).

    1. Hi Taylor and Bill,

      I’m having this same problem with a horizontal scroll bar appearing (if the content is long enough to trigger a vertical scroll bar). I’ve found that wrapping everything in a div and setting overflow:hidden; eliminates the vertical scroll bar (in Genesis I’m using the element for this). I don’t love this solution but it is the best I’ve found thus far. I’ve written a blog post about this at

      Thanks for this post Bill, it’s been a great help.

  8. I forgot to mention — the above scrollbar behavior is visible once you remove gutenberg’s width: content-fit rule which is in effect here on image blocks, but not well-supported.

  9. Thanks for your post. Still wondering if ‘now’ would be a smart moment to get a new theme for my blog, or if it is better to wait until Gutenberg has arrived.

    1. I think now is a great time to get a new theme, as long as the developer is familiar with Gutenberg and has included Gutenberg support, or if it’s a commercial theme and they provide updates that will include Gutenberg support.

      If you’re having a theme custom designed, it takes times (see our sample timeline). Any projects that we book right now will likely start development after Gutenberg comes out. Development is the third stage of Reply

  10. I’ve just read your page on modular templates and was impressed with the functionality you offer that way and the user experience. A page builder alike experience, but within the constrains of a theme’s design, even making sure the content stays available for search and changing themes (like BB does). I follow you in that migrating to Gutenberg, at some point, will be a possibility, when limiting the options that are accessible to what the theme supports. So great example of how to do it, and your customers will surely be glad they found you.

    If Gutenberg doesn’t offer adaptations for different viewport sizes (show/not show, size-adaptations, and so fort ), supporting breakpoints or something better, that would perhaps also be the way to go to guarantee the best presentation on all devices. I understand it is already possible, or will be, to limit the options presented in the editor per block to content creators, from within the theme.

    I expect you are also right predicting further tools for easy and fast block creation.

    I like the wide and full display of images, are there next to align-wide, more options that need their theme-support explicitly declared?

    I also like the extra block-types that are offered standard in Gutenberg, like an image with a title on top, even with a fixed background by only switching a checkbox. Not a difficult thing to make, but having it as a standard block-type is a nice thing, even when there are not that many options (like for changing colors also for different states of buttons) and one may want to use a stylesheet still to adapt it to a theme. But even the default presentation looks quite nice.

    Being able to change the HTML on a block level is a much better experience than having to scroll through a long document just to add a class to something.

    So props to Gutenberg for rocking our world in a good way, enabling a change that can again excite our imagination.

    Thanks for the great examples,


    1. The only two Gutenberg features that require theme-support (that I know of) are wide images and color options. You can specify an array of theme colors that appear anywhere a user can pick a color (button background, text color…).

  11. Hi Bill, thank thanks a bunch for sharing this great examples. Highest time to check Gutenberg Editor. We hope that it comes with a lot of additional values for our customers. Your tipps are very helpful to dig into Themedevelopment with Gutenberg and help me to make a good part with Gutenberg

  12. Is this still relevant and accurate? Meaning; if I add this to my theme, Gutenberg will work?
    My theme is set to a custom width of 1200px.

    1. Some of the blockquote and separator styles have changed a bit, but for the most part, this is still accurate.

      I recommend you install the Gutenberg plugin either locally or on a staging environment and then begin making style changes to get them right.

      I’m building a Gutenberg website right now on Genesis, so will be updating my Genesis child theme over the next few weeks with more Gutenberg updates.

      I’m also writing a new blog post, “Building a Gutenberg theme”, which should be out in a few weeks. If you haven’t already, sign up for email updates so you’ll be notified when that post is live 🙂

      1. Maybe I’m missing something but I can’t find for the life of me anywhere on your website where there is an email update signup form. Or…is it because I’ve commented here, I’ll start receiving email updates?

  13. Thanks a lot for this excellent post – still very relevant, IMHO.
    One thing I haven’t found much info about – Gutenberg does add quite specific styles to its Column element, eg

    @media (min-width:782px) {
    .wp-block-column:not(:last-child) {
    padding-right: 16px

    I wonder if the idea here is to use custom CSS classes to override these settings if/when we need different @media sizes or padding/margin values.

    If there’s a simple way to stop Gutenberg loading these styles, at least in the front end, I haven’t found it yet.

  14. Guttenberg will never survive. It is a disaster. There’s enough bugs in it to consumer every ounce of flesh on this earth. It is “like a box of chocolates and has been for the last 4 month

Leave a comment