How to add WordPress Theme Styles to Gutenberg

How to add WordPress Theme Styles to Gutenberg

Listen to this article:

Voiced by Amazon Polly

In a couple months or so, Gutenberg will revolutionize WordPress publishing as we know it. It’ll finally bring a much-needed standardized content creation experience to WordPress. There’s just one small caveat.

Innovation simply can’t happen without WordPress theme developers committing to the Gutenberg experience. If Gutenberg will become the de facto editing experience for the average WordPress user, why not make it the best experience possible?

So after an inspiring trip to Nashville for WCUS, I decided to jump on the Gutenberg ship myself and start styling the upcoming editor within my latest WordPress theme, Tabor. Here’s how it went, and what I learned along the way.

Edit: Since posting this article, many of the details of applying editor styling to WordPress themes has changed quite significantly. The good news is, I’ve re-written this guide with up-to-date code examples from a couple of my Gutenberg-optimized WordPress themes, Tabor and York Lite — which you may reference on GitHub. Enjoy!

Adding editor style support

If your WordPress theme is not properly optimized for WordPress 5.0, it’ll assuredly become hopelessly obsolete in this post-Gutenberg era of WordPress. Even worse, your theme could end up causing a whole slew of styling issues within the new editor, and even on the front-end.

Love my WordPress theme?

I'm using the Tabor WordPress theme. Add your email address below and I'll send you a $10 coupon for the theme. 🎉

Adding WordPress theme styles to Gutenberg is not as “plug-and-play” as one would think. To start, you’ll want to use the add_theme_support() function to  declare support for editor styles. 

Here’s an example of how I declared support for editor styling in my popular WordPress theme, Tabor:

Next, you’ll want to enqueue your editor stylesheet with the add_editor_style() function. While the above simply declares support for editor styling, this bit will load the actual styles you’ve established into the editor to bring it on par with the front end styling. 

Here’s what we have now:

Apart from registering the Gutenberg-specific stylesheet, theme developers will absolutely need to fine-tune elements within the new editor to ensure that each displays with relative parity to the actual front-end output.

Otherwise, the editor won’t actually look like the front-end at all…

Fine-tuning theme styles within Gutenberg

The biggest issue with applying editor styling, is that block elements have margin and padding that simply do not exist within the theme’s front-end styling. Getting the editor styled “just right” will likely take a number of tweaks and probably a few wacky hacks here and there.

One of the newish features of Gutenberg is that you don’t need to add an obscene amount of prefixes anymore, as the editor will automatically add relevant prefixes to the styles behind the scenes. 🤯

If you’re using SASS (which you absolutely should) then applying styles to the editor is not so bad. You can set a lot of variables and reference those in both the front-end stylesheet and editor stylesheet. For reference, here is the editor stylesheet (SASS) from my York Lite theme. It’ll help if you open that up in another window and follow along.

Styling individual blocks

You can use the .wp-block selector to style every block, or to be more specific, use .wp-block-{name}. For example, to apply a custom editor style to the Author block in my CoBlocks plugin, you’d use .wp-block-coblocks-author

Styling default, full and wide editor widths

Expanding off of the .wp-block selector, we can target the align data attribute, to set the full and wide alignment values to use within the editor. Again, if you’re using SASS, simply throw in your variables for each the wide and full alignments. Check out the following example:

Changing the editor’s typography

You’ll need to first load your fonts within the editor, if you’re using something like Google fonts on the front-end of the theme. If you’re using a function to spin up the selected font URL from Google Fonts (which you probably should be doing), you can simply plug that into the add_editor_style() function, and append it right below where your actual editor stylesheet is added. 

Here’s a full working example from York Lite, with the corresponding font url function – which you can check out right here.

Now that the fonts are loaded, to match the editor’s typography with the theme, you’ll want to target the body and p selectors primarily. Don’t forget to style headings as well, H1 through H6, and ensure they are properly colored and are the correct font sizes.

Styling the page/post title

Adding Gutenberg editor styles doesn’t stop with the main content. We can also target the editor’s title to style it like the page or post title on the front-end; again leveraging SASS so we’re not doubling our efforts. Here’s how:

Potential pitfalls

If your WordPress theme registers its entire front-end stylesheet for the Gutenberg editor, you’ll end up with a complete mess:

What happens if themes don't include styles correctly
What happens if themes don’t include styles correctly

There’s quite a bit of work to be done for these WordPress themes. And from my experience reviewing WordPress themes at Envato — theme developers are notoriously lazy.

Sure, proper editor styles are required for themes uploaded to the WordPress repository, but outside of WordPress.org, it’s the wild west. So if your theme is doing it wrong — fix it now!

Closing

With the release of Gutenberg into the wild, users will come to expect a true one-to-one content creation experience. If a WordPress theme’s editor styling isn’t up to par, the user’s experience is instantly disrupted. Then you’re missing the point of Gutenberg right off the bat: to capitalize on improving the user experience of WordPress editing.

Adding theme styles to Gutenberg is not difficult by any means. But it does take a bit of effort and consideration, to build a beautiful content editing experience on top of Gutenberg. 

Just take a look at this video, which shows how proper editor styles dramatically improve the content creating experience in WordPress 5.0+.

Writing a post using the Tabor WordPress theme

Unfortunately, without fine-tuning the theme styles within Gutenberg, you end up with a what-you-see-is-probably-close-enough-to-what-you-get experience. Not the promising editing experience we’re all shooting for.

I encourage all theme developers to experiment with adding WordPress theme styles to Gutenberg. Let me know when you do, as I’m curating a collection of “actually” Gutenberg-ready WordPress themes — and I’d love to see yours!


Also published on Medium.

  1. Looks like it’s similar to enqueue editor style for tinyMCE. It would be great if the docs for all default block styles are available. It’s hard to style just by inspecting elements.

    1. I had the same thought. I pulled unminified CSS directly from Gutenberg front-end styles (link below). It’s certainly helpful for front-end styling but doesn’t capture everything in the editor (for example, I’m currently slogging through how to apply custom button styles in the visual editor to buttons, but not to Gutenberg’s component buttons. There are some additional classes available to target to help with this, but they’re not accounted for in the front-end stylesheet output by Gutenberg).

      Rich’s suggestion of wrapping all editor styles in a `.edit-post-visual-editor` is a big step in the right direction though.

      https://gist.github.com/cdils/a2f1d4f9408b4870f82f5c96e6f62c65

  2. Rich do you think that styling all the theme assets to a what you see is close enough is even worth it? It is a premature question, but isn’t the goal to have Gutenberg expand into the Customizer next? I came back to this article to review what you have done because I am trying to consider if I’m going to wait out porting my work to Guetenberg until they get it in the customizer. Nearly all my client sites use the front-end editor for posts and the backend for CPT / Pages.

    1. Hi Jake. I do.

      I don’t know at what point Gutenberg and the Customizer will merge, what that will look like, or even what it’ll encompass — but I do know that if a theme’s styling and Gutenberg doesn’t line-up, it’s not great for the user.

      It’s a lot of work though, at least to get it really good. I’m doing it for my project, Writy.io, and a couple of my blog/writing themes — but I won’t do it for all of them just yet.

  3. Thank you!

    I finally watched the LoopConf video by Mel Choyce last night which showed off ideas of how the future might look. I really hadn’t turned the corner that the customizer is the front-end.

    https://goo.gl/k9Hj3N

  4. I came across this post looking for a way to add my theme’s stylesheet to the editor the way we did for tinymce. You’re right that adding the stylesheet to the entire interface is a mess! Is there not a way to add the stylesheet just to tinymce elements in Gutenberg? I like Gutenberg so far but am frustrated by the lack of documentation. It’s making it too difficult/time consuming to test it out ahead of launch.

    1. Hey Greg! Yea, there’s not a way to append a stylesheet to just the proper elements within Gutenberg. It’s definitely a bit tricky at the moment, though I don’t suspect it’ll get much easier.

  5. How would you go and add dynamic customizer styles to the gut. editor?
    Thinking of adding some basic customizer based colors such as button background colors and body background color etc.

    1. I’m honestly not sure how we’d be able to communicate those dynamic styles. Maybe adding the Customizer’s inline styles to display within the Gutenberg editor, with the Gutenberg-relative selectors within in? ¯\_(ツ)_/¯

  6. Oh man dude. This is great. I’ve been looking for a solution for this for weeks. It looks like Gutenberg is here to stay, so might as well prepare for it right!

    Also, design shoutout — this theme is dope! Very nice and polished.

  7. I’m working on a ground-up theme build with a bunch of custom blocks (most of them to replace those page-builders for the homepage and other complex pages). The biggest challenge so far – on smaller screens admin ui elements (read side panels) take up so much screen estate that the actual page becomes so narrow that it would switch to the tablet layout, should it be on front-end. Except just adding a horizontal scroll for the whole editor view to let the user edit the desktop layout I can’t come up with a acceptable solution. Any ideas?

    1. That sounds like an interesting project Alex. ?

      If you have a lot of admin UI, it may be best to pull them out in a pop-up of sorts, or work in a clever way to toggle views via the Block Controls.

      On my CoBlocks plugin, I have a Gist block which I’ve added a toggle control (the “info” icon on the screenshot here, which when clicked brings you to the Gist URL view you see right above the actual gist in that screenshot.

      Maybe something like that could work?

  8. By admin UI, I mean native WordPress menu panel at the left and Gutenberg’s document/block settings panel at the right of the page. On typical 13′ macbook this leaves us with only 740px for the actual page content.

    So here’s the fundamental issue: a page cannot look the same in editor (in 740px container) as it looks on front-end (1280px width on the same screen).

    That definitely defies the idea of having an “almost-wysiwyg” editing experience.

    1. Ah, I see what you mean. Realistically, blocks don’t have to use the Inspector region — if you can figure out a creative way to add options and settings via block views or pop-overs.

      Eventually Gutenberg will likely exist within the Customizer sidebar, so that’ll save a bit more horizontal space — but as it currently stands, we need an Advanced Settings area, for uncommonly used block settings.

      ¯\_(ツ)_/¯

    1. Hey Frank,

      There’s been a lot of changes (and ongoing changes even) to editor styling. The styles still load using this method, but there is work being done to improve the process by automatically adding proper prefixes to editor-styles. I’d honestly suggest waiting another week or so before doubling down on editor styles, as it should be cleared up a bit more then. ?

  9. Thanks for your contribution to this new way of development.

    I have a pretty neat fix for not messing up the whole admin area with your styles but still be able to include all of them in an easy way.

    The only requirement is that you already have a sass build.
    Then instead of enqueue your main.sass / css, make another “admin.sass” and include the “main.sass” like this:

    _admin.sass_
    /* NEST FOR BLOCKS EDITOR */
    .edit-post-visual-editor {
    @import “main”;
    }

    With this, all styles will only apply to the gutenberg visual editor.
    Then only enqueue the generated admin.css.

    Work great here!

    Enjoy 😉

    1. Thanks Gilles! While this is an interesting method, you end up inserting a lot of styling that is unnecessary for the editor. I’m actually working on an update to the post with a few new methods I’ve started deploying throughout my themes. Using SCSS is a necessity for sure though. Otherwise it’s very difficult to keep styles synced up.

      1. I think I’ve found another way around this issue: I enqueued an admin-fix.css file along with the main stylesheet, so no need for prefixing in a separate css.

        Basically, you revert the mess that the enqueued stylesheet caused, simply by adding a couple of css rules. For me, that was just couple of lines:

        .edit-post-sidebar,
        #adminmenu { font-size: inherit; }

        .edit-post-sidebar ul, .edit-post-sidebar ol,
        #adminmenu ol, #adminmenu ul { padding: 0; }

        .edit-post-sidebar button,
        #adminmenu button { font-size: inherit; line-height: inherit; color: inherit; }

        .edit-post-sidebar a:hover,
        #adminmenu a:hover { color: inherit !important; }

        Now I don’t have to worry about maintaining two css files that basically have the same rules in it.

  10. Maybe I’m wrong, but if Gutenberg’s goal is to match front-and-back-end (styles) then both the theme and G editor should share the same (ONE) stylesheet file. But it kinda sounds impossible…

    Next problem… what’s the point of using Customizer for styling theme’s typography if there’s no way to apply changes to Gutenberg editor too? And what sense does make the effort of making front-and-back-end match each other visually from the Customizer point of view?

      1. OK Rich, great, that’s a clue! Didn’t know about an inline-style option, didn’t think of it at all, it’s definitely better than nothing. Woohoo, thanks!

  11. Hi Rich.
    In your post you said, “I’m curating a collection of “actually” Gutenberg-ready WordPress themes”. Did you ever curate a list of Gutenberg ‘actual’ ready themes? I’ve been looking for such a curated list that don’t rely on 3rd party page builders.
    Thanks,
    Michael

        1. The #1 bit would be proper editor styling so that the theme’s front end and editor instances look one-to-one. Apart from that, themes can add custom font sizes relative to it’s own typographic scale, custom color palettes, and support for wide/full alignments.

Leave a Reply

Your email address will not be published. Required fields are marked *

 

Up Next:

5 Key Takeaways from WordCamp US 2017

5 Key Takeaways from WordCamp US 2017