Bill Erickson

Blog / Gutenberg Block Editor

Adding Gutenberg support to WordPress theme

Written by Bill EricksonPublished on February 26, 2018Updated on June 20, 2023

WordPress 5.0 shipped with a brand new, block-based content editor named Gutenberg. It is a huge improvement for content editing, and will become even more powerful as more blocks are built in core and in plugins.

All WordPress themes work with Gutenberg. It’s simply a new interface for creating content.  No changes are required to your theme to display your new block-based content.

However, there are some new features that your theme can take advantage of with minor updates. Also, the content editing experience can be improved with additional styling in the theme to ensure the backend block editor matches the frontend styling of the theme. 

I’ll guide you through updating your current WordPress theme to support these new features. If you’re not a developer and need help, I recommend you use Codeable – they are fast, knowledgeable, and affordable.

Developer's Guide to Gutenberg

I walk you through the technical details and code snippets you need as a WordPress developer building a Gutenberg website.

Read More

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 your theme to style these alignments. See my guide to wide and full image alignment in Gutenberg.

Blockquotes

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.

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

/* Blockquote
--------------------------------------------- */
blockquote,
blockquote.wp-block-quote {
background: transparent;
text-align: left;
p {
font-size: 24px;
font-style: normal;
font-weight: 400;
}
cite,
.wp-block-quote__citation {
display: block;
font-size: 16px;
font-weight: 700;
margin-top: 12px;
text-transform: uppercase;
}
p:last-of-type {
margin-bottom: 0;
}
&.is-large,
&.is-style-large {
margin: calc( 2 * $block-margin ) auto;
p {
@include font-sizes( 24px, 36px );
}
}
}
/* Pull Quote
--------------------------------------------- */
.wp-block-pullquote {
border: none;
padding: 0;
blockquote {
border-left: 0;
border-top: 8px solid $highlight;
border-bottom: 8px solid $highlight;
padding: 16px 0;
text-align: center;
max-width: 50%;
margin: 0 auto;
}
&.alignleft,
&.alignright {
blockquote {
max-width: 100%;
}
}
}
view raw _blocks.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. There’s a few different styles of horizontal rules built into the editor: default, dots, and wide. Here’s the base SCSS I’m currently using:

/* Separator
--------------------------------------------- */
.wp-block-separator,
hr {
&:not(.is-style-dots) {
background-color: $border-color;
border: 0;
height: 1px;
}
&:not(.is-style-wide):not(.is-style-dots) {
width: 100%;
height: 4px;
background: transparent;
&::before {
content: '';
display: block;
height: 4px;
width: 40px;
background: $highlight;
}
}
&.is-style-dots:before {
color: $grey_9;
font-size: 18px;
letter-spacing: 12px;
padding-left: 12px;
}
}
view raw _blocks.scss hosted with ❤ by GitHub

Buttons

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.

For more information, see my Guide to Color Palettes and Button Styling.

/* Button
--------------------------------------------- */
.wp-block-button {
.wp-block-button__link {
border-radius: 0;
font-weight: 700;
font-size: 16px;
line-height: 18px;
padding: 20px 24px;
&:hover {
background: darken( $highlight, 10% );
text-decoration: none;
}
}
}
view raw _blocks.scss hosted with ❤ by GitHub

Backend Styles

There are two ways you can add your theme styles to the Gutenberg block editor.

Option 1: Editor Styles

Your theme likely has editor styles added to make the classic editor more closely resemble the frontend. By default these are not loaded in Gutenberg, but you can turn it on.

WordPress is smart enough to automatically transform your styles so they only affect the block editor. With this approach, you can define a single set of styles that apply to both the classic and block editors. This is my preferred approach.

// Editor Styles
add_theme_support( 'editor-styles' );
add_editor_style( 'assets/css/editor-style.css' );

The add_theme_support( 'editor-styles' ); tells WordPress to load the editor styles in the Gutenberg block editor. Without this, they would only load in the classic editor (TinyMCE).

The second line, add_editor_style(), is the path to your editor stylesheet.

See my base theme as an example.

Option 2: Enqueue Block Editor Assets

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 .editor-styles-wrapper class to ensure it only applies to the editor (not the WP backend menu, metaboxes…).

SASS

Whichever approach you choose, I recommend using SASS partials. This will let you write your styles once and compile them into both the frontend and block editor stylesheets as necessary.

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

  • I’m only including relevant styles from the main stylesheet (style-guide 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.
  • In the Gutenberg partial I’m setting the max width of blocks to match the site’s max width on the frontend ($content-width is defined in _base.scss)

Custom Blocks

While the core blocks are powerful, they may not serve all of your content creation needs, especially when it comes to complex pages like your homepage and landing pages.

Most of the sites I build include 6-12 custom blocks. You can build custom blocks with Advanced Custom Fields (my recommendation), or with JavaScript. You can also leverage block libraries like Atomic Blocks and Jetpack for additional block options.

Any more tips?

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

Bill Erickson

Bill Erickson is the co-founder and lead developer at CultivateWP, a WordPress agency focusing on high performance sites for web publishers.

About Me
Ready to upgrade your website?

I build custom WordPress websites that look great and are easy to manage.

Let's Talk

Other articles in this series

A starter theme for building Hybrid WordPress Themes

May 29, 2023

A hybrid WordPress theme uses theme.json to define styles and customize the block editor while also using traditional PHP template files. Hybrid themes leverage the block editor for content but…

Building ACF blocks with block.json

August 25, 2022

ACF 6.0 includes a major improvement to the way blocks are built. It now supports using block.json, which aligns with WordPress core’s preferred method for block registration. Why is this…

How to remove core WordPress blocks

June 25, 2020

While I try to support all the core blocks in the themes I build, sometimes it makes sense to remove a few. Typically it’s because I built a custom block…

Reader Interactions

Comments are closed. Continue the conversation with me on Twitter: @billerickson

Comments

  1. Taylor says

    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.

  2. Joost says

    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.

    • Bill Erickson says

      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

      Hans Schuijff says

      June 30, 2018 at 4:43 am

      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,

      Hans

      • Bill Erickson says

        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…).

    • Jennifer says

      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

    • Bjornen says

      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.

      • Bill Erickson says

        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 🙂

    • Phil says

      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(:first-child){
      padding-left:16px
      }
      .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.

    • Philip Whitneyh says

      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

      • Paul says

        I wouldn’t mind it but the developers seem really closed to criticism. I suggested they should make it more intuitive and the reply I got was very defensive. Reading through some of their replies to other suggestions made me skeptical this is going to work out well for everyone…

    • Jane says

      Thanks for explaining the blockquote blocks and options! Gutenberg partially converted my blockquotes, but not fully (style elements are missing), and now I have a better idea of how to fix them.

    • Muskie says

      I’m trying to get tall skinny images to float to the right and they do so in the editor as I expected but in my theme they do not float around the next block. I have been looking for some CSS to solve this of course.

    • mfs says

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

      Makes sense. But have you seen SASS being used to do this? Or maybe I’m not quite getting “it” yet as I’m just finally climbing the Gutenberg learning curve?

      For example, the WP.org tutorial starts with a simple text block. It then shows how to do add an editor style, as well as a frontend style. But, at least in theory aren’t they ideally the same (or damn close)? That is, if the user were to set the font size to e.g. 30px, in a particular font, isn’t the idea that Gutenberg is a true WYSIWYG?

      Unless I’m not finding something yet, a block is going to have two style sheets, and despite the fact there are (nearly) identical, the developer has to maintain both (with the editor css having .editor-block-list__block prefixed. )

      tia –
      mfs

      • Bill Erickson says

        Yes, you can use SASS with either option listed above (using editor styles or loading a separate stylesheet).

        The benefit to the editor style’s approach is WordPress auto-prefixes everything for you as needed so you can start with a cleaner stylesheet.

        Take a look at my two starter themes. The editor stylesheet only contains a few partials:

        @import "partials/base";
@import "partials/blocks";
@import "partials/gutenberg";

        While the main site’s stylesheet contains those and many others:

        @import "partials/base";
@import "partials/reset";
@import "partials/form";
@import "partials/blocks";
@import "partials/layout";
@import "partials/site-header";
@import "partials/navigation";
@import "partials/archive";
@import "partials/singular";
@import "partials/site-footer";

        I only write the relevant styles once. If I’m styling the “button” block, that goes in _blocks.scss which is loaded in both editor-style.css and main.css.