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.

Adding WordPress theme styles to Gutenberg

If your WordPress theme does not properly support editor styling when WordPress 5.0 ships next year, it’ll be hopelessly dated as soon as Gutenberg launches. Even worse, your theme could cause a whole slew of styling issues within the new editor.

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 enqueue a separate Gutenberg stylesheet using the enqueue_block_assets action.

Here’s an example of how I added Tabor’s theme styling to Gutenberg:

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 is that block elements have margin and padding that simply do not exist within your theme’s front-end elements. Getting the editor styled “just right” will likely take a number of tweaks and wacky hacks.

I ended up prefacing nearly all of the custom theme styles with the .body.gutenberg-editor-page class within Tabor’s Gutenberg stylesheet. Then I went in and started targeting the various textareas to try and get the editor as close as I could to the actual front-end output. 😅

Here’s a quick demo video of the results:

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 you were hoping for.

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 imminent release of Gutenberg, 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.

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!

  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.

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