The State of Gutenberg and WordPress Themes

…or

“A Realistic Look at Using 3rd Party Gutenberg Blocks in Your Theme”

…or

“Keep Your Plugin Blocks Out of My Theme”

…or

“Shortcodes All Over Again”

…or

“The Never Ending Battle to Style a Button Consistently”

…or

“We Still Have a Long Way to Go”


I would like to preface this article by saying that these thoughts and opinions are in no way meant to diminish the amazing work that the Gutenberg team has done (and continues to do). I love writing in Gutenberg. I follow the GitHub repository closely, often reading 100+ notifications each day. I have been testing since early versions. I have left feedback. Things have gotten much better. However this article is meant to take a realistic and somewhat critical look at how Gutenberg is being presented on a grander scale vs. some of the realities that come in to play when implementing these ideas.


What You See is (Maybe) What You Get

WYSIWYG is everyone’s white whale but Gutenberg takes a huge step in the right direction towards helping publishers have a better idea of what their content will look like as they are writing. The previous (technically still current until WordPress 5.0) iteration of the WordPress editor powered solely by TinyMCE fell short in a lot of areas in this regard. Over time the introduction of custom CSS editor styles and shortcode previews helped, but things never were quite right.

  • Not all themes implemented a complete transport of their frontend styles to match the editor.
  • Not all themes properly set the editor content width to match the frontend (also who has just one width point these days?).
  • Not all themes even felt the editor was an important part of their functionality (it’s not for most of my themes).

And honestly I don’t think there was ever been a strong feeling that TinyMCE was ever truly WYSIWYG. I have never had that expectation.

Gutenberg’s take on WYSIWYG is different. It does hold true that exactly what you see while writing is what you will see when you view your published post. Setting this expectation is very risky, and I think will ultimately cause a lot of frustration for both users and developers.

Bypassing WordPress’ Most Valuable Feature

One of the major concerns I’ve had with Gutenberg from the start is with Javascript. But not because Gutenberg is using Javascript. I think that is great; and it’s helped me transform my almost non-existent Javascript writing to almost a daily occurrence. What frustrates me is the complete reimplementation of much of what makes WordPress so nice to develop for in the first place: the templating system + hooks and filters.

Starting from scratch and creating a block for something that previously did not exist on your website might not surface this issue, but as soon as you want to convert an existing shortcode to a Gutenberg block this shortcoming becomes very apparent. The ServerSideRender component was introduced to help mitigate these issues, but its introduction brought a stern warning against it:

ServerSideRender may also be used when a legacy block is provided as a backwards compatibility measure, rather than needing to re-write the deprecated code that the block may depend on.

ServerSideRender should be regarded as a fallback or legacy mechanism, it is not appropriate for developing new features against.

In my opinion this is not a necessary statement to make and assuming all code that currently exists in a theme should be deprecated (which is how I interpret it) is just wrong. Without using a ServerSideRender component Gutenberg will likely not be WYSIWYG for a very long time.

See the WooCommerce [products] shortcode. WooCommerce is working on a Gutenberg implementation of this shortcode. However in my opinion they are going about it the wrong way. When using that block the user is presented with a “preview” (hard-coded in Javascript) of the products they have chosen to display.

I see something like this while writing:

This looks absolutely nothing like what I see when I publish the page:

Because the block is using Javascript to manually create a preview of the block it never touches the theme code. It has no idea that I don’t display the “Add to Cart” button at all. It has no idea I’m using a custom template file for my sales flash. It has no idea I output the ratings in the loop.

Now the theme author has an issue. There is no way for the theme to tell the block “Hey, this is actually how the theme displays products” — the only enhancements that can be made are minor CSS tweaks.

One might say that a filter could be added around the preview HTML output in Javascript (here), which is true. Then the theme author has to create their own Javascript file to implement the filter (likely requiring a build tool setup), pass their theme display options to the script via wp_localize_script() and adjust the output accordingly. However once they make a change to their content-product.php they then need to mirror that change to their Javascript template file. Rinse and repeat.

Then one might say that a Javascript template could be used on both the frontend and in the editor if the [products] shortcode was implemented in Javascript on the frontend as well. This is true, but would be a breaking change as existing content-product.php template files won’t work, and general customization becomes much more complicated.

If instead the block simply rendered a server side preview of the existing shortcode all the changes my theme has meticulously implemented would be reflected without changing the [products] shortcode or my theme files.

I Don’t Like Your Styles

Gutenberg recently shifted to have block theme/presentational styles opt-in. This was a great step and was done as it became apparent that block appearance was quickly shifting apart in the editor and the frontend. However most distributed block plugins I have seen currently do not do this. Styles are registered and used automatically; once again creating a completely different appearance in the editor and on the frontend.

My theme does not have any other buttons like this.

Theme authors have a bit more control this time around. Styles can be dequeued, CSS can be written again to work with the plugin’s chosen class names, and everyone is happy. Until the user installs another block plugin. Then the poor theme author ends up with some monstrosity like this:

… and then repeated for the frontend styles. Not great. At all.

In my mind theme authors have a few choices:

Ignore the issue

¯\_(ツ)_/¯

Try and maintain support for every plugin your user requests

¯\_(ツ)_/¯

Pick a set of 3rd party blocks you officially support and style for

Gutenberg does provide the ability to whitelist the blocks that are available. This ensures the theme author only properly styled blocks can appear. However this comes at the expense of the user. Now they are left confused when a block they just potentially paid for is not usable. Or they become confused when they switch from one theme to the next and suddenly are offered more blocks (or less).

Recreate the blocks they think their users want in the theme

This is basically what happened in 2012-2014 at the height of “stuff everything AND the kitchen sink” in to the theme. Every theme offered their own implementation of 100+ shortcodes that they could have total control over and ensure would be styled to match their theme. I predict this is what will happen with blocks.

Using a prebuilt solution can be extremely valuable on larger scale things like WordPress itself, WooCommerce/Easy Digital Downloads for commerce, Jetpack for some extra cloud based functionality, etc. However relying on a plugin that may not always be available and that you cannot guide or control can end up costing more headache and time in the end. If the author is unable or unwilling to make a change you feel necessary to facilitate a better experience in your theme you end up having to recreate it yourself anyway.


None of these are great; and I don’t have any better ideas.

Think Before You Code

The next few months will see plugins scrambling to create a block to “stay relevant”. I think a lot of this will be done without warrant and will end up with an even worse user experience than before. Not everything can fit in a block no matter how hard you try. This is especially true while the core editor still develops its UI flows and components for more advanced interactions.

Before attempting to go “all in” with blocks think about what enhancements exposing an inline block editing interface provides. Does it provide any at all? Or are you going to end up with a convoluted UI to solve a problem that doesn’t exist?

A few toggles to help generate your shortcode arguments and a live preview (a true preview provided by ServerSideRender) in the editor is what the Shortcake project was meant to achieve. We have that now! Relatively easily! It’s okay to leave it at that. Your user has no idea nor do they care how the block is being rendered; they just want it to be accurate.

My Thoughts and Predictions

It’s very possible I’m over analyzing, overthinking, or just plain wrong about some of this (and correct me if I am!); but those are my thoughts as I’ve watched things unfold over the past 6 months.

As I mentioned at the start — I really do like Gutenberg. This post was written in Gutenberg. I shared the Gist embed via a Gutenberg block (CoBlocks). This is where Gutenberg excels. I realize it’s a bit early to judge the plugin beyond that since development is still in the first phase which is meant to focus on writing (contained in the editor). However I do think it is fair to manage expectations for the merge in to WordPress 5.0 — which was April, now August — and I predict a few months after that.

In my mind Gutenberg needs to shift away from treating shortcodes and widgets as the red-headed stepchild. 15 years of WordPress is built on them. Documentation should shift away from calling them old and legacy. The main reason is because they are not — WordPress 4.9.x introduced new brand new widgets and they were touted in the release posts. Next because as it currently stands Gutenberg cannot really provide the level of frontend and editor integration a lot of people expect without utilizing those existing structures and rendering them on the server.

Distributed Blocks and Themes

I predict once things settle down a bit advanced blocks that truly integrate with themes will rely heavily on the ServerSideRender component to provide a more seamless experience for users. And I think this is a good thing. Smaller publishing-focused blocks like stylized content components, custom embeds, etc will do very well as “true” blocks since they have always easily been theme-agnostic.

I predict themes will start building and bundling (or the closest thing to it) their own blocks to avoid having to rely on or work around other developers.

I predict users will still have a lot of friction achieving a true WYSIWYG experience.

Next Steps

I am working on a follow up post to demonstrate how I believe a server rendered block can provide publishers with the valuable previews they desire without putting extra burden on theme authors.

My Current Take

BigBox is fully compatible with Gutenberg — but it stops there currently. I have not decided the route to take for 3rd party blocks.

Powering BigBox

Techniques like this and many more power the highly flexible and highly optimized BigBox WooCommerce theme.

Get BigBox Today →


Interested in learning more? Subscribe below to get notified of new posts and exlusive content.


4 replies to “The State of Gutenberg and WordPress Themes”

  1. Happy to see this all put in writing. These questions have been at the back of my mind, but I haven’t had an opportunity to really dive in. It’s very disappointing that actually none of this seems to have been given much thought. It’s, er, notable that these aren’t issues that need as much consideration when you’re in, say, an environment where users can’t install plugins and can only use a smaller set of pre-constructed themes.

    All the problems for theme authors you mention are going to be even worse when you’re at an agency and developing completely bespoke themes for every site. Achieving true WYSIWYG in Gutenberh with 3rd-party plugin compatibility for each theme seems to be nigh on impossible for anything short of very high budget projects. If that’s impossible then what even is the point of Gutenberg for that kind of site? When the same flexibility is achievable considerably easier when you forgo WYSIWYG and use something like ACF?

    1. I definitely agree. So many data-driven sites are much easier to use when the user is presented with a simple form to complete. When content is added by users who have no concern for the output and are just logging information WYSIWYG can become a burden.

      1. Completely agree here. Gutenberg will likely prove itself really useful for certain use cases, but at the expense of others. I find it interesting that Drupal recently implemented a first pass at a similar project (called Layout Builder), but it’s opt-in. You can use it, or continue using a custom-field approach like we would do with ACF. Forcing Gutenberg as the only core option is I think what is causing the friction in the community, burning a lot of developer bridges, and will quite possibly be the cause of market-share lost to other platforms, like Drupal, especially for enterprise clients.

  2. I agree, it’s a bit of a sticky situation with themes needing to basically re-implement all their rendering in JS and PHP. Not sure what the solution is there… but I think it’s good to start a conversation about it. Thanks for putting your thoughts out there!

Leave a Reply