Hey WordPress Theme Developers, Are Your Themes Ready for the Gutenberg Block Editor?


Before WordPress 5.0 arrived I came across a few premium WordPress themes already advertising that they were ‘Gutenberg-ready’ or ‘Gutenberg-compatible’. Huh. But how could a theme not be compatible with the new block editor (formerly known as Gutenberg)? Surely themes just render whatever is in the post content with the theme’s own styling?

Turns out there’s a bit more to it than that. In this post I’ll walk through what is necessary to make existing themes or create new themes that fully support the block editor.


After venting on Twitter about theme shops using Gutenberg compatibility as a marketing tactic (pro tip: don’t tweet hangry), I was kindly educated by Rich Tabor about the extra layers of support themes can add to make the experience of the block editor even better.

Admittedly I’ve been in the plugin development world for so long (I even wrote about making plugins ready for Gutenberg), that the intricacies of theme development have somewhat passed me by. But it’s time to level up, Iain! 💪

I still believe that ‘compatibility’ is the wrong term, as it implies that other themes simply won’t work with the block editor – which is not true. Users won’t have as nice as an experience as with themes that fully support the editor, but they won’t break. This is supported by the ‘Theme Support’ page of the Gutenberg handbook:

The new Blocks include baseline support in all themes, enhancements to opt-in to and the ability to extend and customize.

This guide is a great place to start when making your themes ready for the block editor, but I wanted to pick out a few key areas which I think are important.

Editor Styles

Editor Styles was introduced back in WordPress 3.0, allowing themes to bundle CSS files that altered how the content was displayed inside the editor, giving users a truer WYSIWYG experience while crafting their content.

This approach has been used for years to improve the look of content in the TinyMCE classic editor, but it becomes even more important now with the block editor to get full parity between the appearance of content in the editor and how it is displayed on the front-end of the site.

To tell WordPress to use your editor styles you need to add a call to add_editor_style to the theme’s functions.php, typically in a callback hooked to the after_setup_theme action:

function my_theme_setup() {
    // Lots of other code …

    // Enqueue editor styles.
    add_editor_style( 'style-editor.css' );
add_action( 'after_setup_theme', 'my_theme_setup' );

Then create the style-editor.css file in the root of your theme, alongside the main style.css. The content of this new stylesheet is then down to how the theme looks. Block styles aside, you would normally add base styles for typography to match the fonts, weights, sizes and other styles matching the front-end styling.

Let’s tackle blocks. If we take a look at the style-editor.css file of Twenty Nineteen, the shiny new theme introduced with WordPress 5.0, we can see it is customizing the look of a number of blocks in the editor:

  • Heading
  • Paragraph
  • Table
  • Cover
  • Gallery
  • Button
  • Quote
  • Pull quote
  • File
  • Verse
  • Code
  • Separator

I won’t go into the custom styles for each one, but if we take a look at the quote block as an example. This is what a quote looks like on the site:

Quote block in front-end

Without the theme defining editor style CSS for the block, when you edit the quote it looks different:

Quote block in editor without styles

However, with this editor style CSS, things look pretty much the same as the front end:

.wp-block-quote:not(.is-large):not(.is-style-large) {
    border-left: 2px solid #0073aa;

.wp-block-quote.is-large, .wp-block-quote.is-style-large {
    margin-top: 2.8125em;
    margin-bottom: 2.8125em;

.wp-block-quote.is-large p,
.wp-block-quote.is-style-large p {
    font-size: 1.6875em;
    line-height: 1.3;
    margin-bottom: 0.5em;
    margin-top: 0.5em;

.wp-block-quote cite,
.wp-block-quote footer,
.wp-block-quote .wp-block-quote__citation {
    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", "Oxygen", "Ubuntu", "Cantarell", "Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif;
    font-size: 0.71111em;
    line-height: 1.6;
    color: #767676;

Quote block in editor with styles

Theme editor styles really make the block editor a truly WYSIWYG editor and gives the user an editing experience that manages their expectations of how their content will look.

Twenty Nineteen customizes the width of the editor. It also styles the widget blocks for categories and archives. If you need a full list of all the blocks available in WordPress core then this theme unit testing file has them. Hat tip Morten Rand-Hendriksen.

As with most things related to WordPress theme development, the default themes are a good starting point. Use Twenty Nineteen’s editor styles as an example of what can be styled and then tweak it depending on your own theme’s bespoke look. Twenty Nineteen is based on both the _s and gutenberg-starter-theme themes which are well worth checking out.

If you’ve used editor styles in the past for the classic editor, it’s important to take a look at how things are different for targeting block editor elements in WordPress 5.0.

Color Palettes

Color Palettes is a new feature introduced with the Gutenberg project. Some blocks have controls to change colors of elements of the block display.

The block editor provides a default palette of colors for users to choose from, but themes can add their own default palettes, registered using the editor-font-palette theme support. Let’s take a look at what Twenty Nineteen does:

            'name'  => __( 'Primary', 'twentynineteen' ),
            'slug'  => 'primary',
            'color' => twentynineteen_hsl_hex( 'default' === get_theme_mod( 'primary_color' ) ? 199 : get_theme_mod( 'primary_color_hue', 199 ), 100, 33 ),
            'name'  => __( 'Secondary', 'twentynineteen' ),
            'slug'  => 'secondary',
            'color' => twentynineteen_hsl_hex( 'default' === get_theme_mod( 'primary_color' ) ? 199 : get_theme_mod( 'primary_color_hue', 199 ), 100, 23 ),
            'name'  => __( 'Dark Gray', 'twentynineteen' ),
            'slug'  => 'dark-gray',
            'color' => '#111',
            'name'  => __( 'Light Gray', 'twentynineteen' ),
            'slug'  => 'light-gray',
            'color' => '#767676',
            'name'  => __( 'White', 'twentynineteen' ),
            'slug'  => 'white',
            'color' => '#FFF',

This is the palette in action for customizing the overlay color of the cover block:

Color palette for customizing the cover block overlay color

You can also stop users from selecting other colors that aren’t defined in the palette using this code:

add_theme_support( 'disable-custom-colors' );

Your theme can also define specific font sizes to be used in the editor, which can help keep control of the font style to your theme’s style.

Front-End Styles

There a few extra functions that themes can support to add support for the block editor on the front-end. The most important is adding support for the default block styles:

Core blocks include default styles. The styles are enqueued for editing but are not enqueued for viewing unless the theme opts-in to the core styles.

If you don’t want to go to town carefully crafting how blocks should appear inline with your theme’s bespoke style, it’s probably a good idea to fall back on the core styles using this code:

add_theme_support( 'wp-block-styles' );

A number of blocks have the option of “wide” or “full” alignment, but this won’t be respected when the block is displayed unless the theme opts in using this theme support directive:

add_theme_support( 'align-wide' );

Similarly, any embed blocks won’t be responsive unless the theme supports it:

add_theme_support( 'responsive-embeds' );

Front-end block styling can be as simple or as in-depth as you want it to be and, again, the default Twenty Nineteen theme’s style.css is the best source of inspiration.

Default Themes

Twenty Nineteen, as we have seen, was built with the block editor in mind. But what about all the other default themes of the past, which many sites will still be using? Good news, these have all had an update to support blocks in both their editor and front-end style CSS files.

Going Further

I’ve talked about styling blocks in the editor and on the front-end, but, as Morten Rand-Hendriksen asks, what about modifying the behavior of blocks?

Block filters make it possible to add further settings to a block. But Morten raises a good point – is this the responsibility of themes?

In recent years, functionality like defining custom post types has been moved out of the remit of themes and firmly into the responsibility of plugins. Which is the same for creating new blocks. But is this the same thing? As the block editor, and the ecosystem around it matures, this will become clearer, but I think for now we will see themes altering blocks where necessary.

Wrapping Up

Like with plugin development, the introduction of the block editor has created some challenges and opportunities for theme developers. Themes can really embrace the block editor and give users a seamless experience between viewing their content as they edit and viewing it.

Have you already made your themes block editor ready? Have I missed any tips for a successful approach? Are you making your theme’s user experience even better because of the block editor? Let us know in the comments below.

About the Author

Iain Poulson

Iain is a WordPress and PHP developer from England. He builds free and premium plugins, as well as occasionally blogging about WordPress. Moonlights as a PhpStorm evangelist.