Do Not Build Theme-Specific Block Plugins for WordPress, Please

A few days ago, I came across a small library of blocks. As always, I was interested in seeing what this new plugin brought to the table. Would it surprise me with a block that has not been done before? Would it present a new take on some old ideas? Or, would it be the same old set of blocks that every other block bundle has? Regardless of what it offered, I was excited to try it all the same.

As I clicked on the description to find out more, I was immediately let down. The plugin specifically stated that it was built for only one theme. I could not use it with my preferred theme.

This was not the first time I had run across this issue. Other theme authors have built their own block bundles in the past. The plugin was not bringing anything particularly new to the WordPress community. It had less than a handful of blocks that had already been done before in numerous other plugins.

The problem was that this felt all too familiar.

Over the years, the WordPress community has created a set of unwritten rules regarding what belongs in a theme vs. what belongs in a plugin. Custom post types, taxonomies, and shortcodes are plugin territory. To an extent, widgets should also be exclusive to plugins. However, because of the way they are handled under the hood, there was always an argument that it was OK for themes to register them.

This theme vs. plugin argument has been ongoing for at least a decade. Because of how themes work, such arguments have been a losing battle. Except in a few edge cases, themes could do everything that a plugin could do. However, there was always supposed to be a clear-cut distinction between the two. Themes were meant to handle the front-end design of a website. Plugins were for everything else.

Today, the WordPress project and its block system are making progress toward solidifying that distinction.

Because of WordPress’s legacy of having various parts that did not all quite fit together in the past, it has created a culture of developers building in-house solutions. Nearly every large theme development company has its own plugins for overcoming the platform’s shortcomings. Most of the blame for this lies with the WordPress project. However, the project’s move to blocks is creating a standardized system that handles everything from a paragraph to the overall site container. With standardization across the board, there will be less and less need for these custom solutions from every theme company.

The block system set a clear line in the sand. It removed the need for shortcodes — good riddance — and will soon phase out widgets. Blocks should be putting those old questions to bed.

For clarity, there is little difference between bundling blocks with a theme and building a separate plugin that only works with a specific theme. The end result is the same. Such a plugin would lock a user into sticking with that theme if they relied on the plugin at all. Few people maintain the same front-end design forever.

The goal is to allow users to switch themes at will while having access to their content and blocks.

These theme-specific block plugins are thinking about blocks in the wrong way. When a user installs a block plugin, the expectation is that they can use those blocks regardless of their theme.

The solution for themes is to use block patterns or styles. Suppose that you wanted to create a slider or carousel as a theme author. There are multiple solutions for this. The first and easiest is to simply recommend a plugin to users or build a plugin of your own that works with any theme. You could also easily add a slider style for the Gallery block. When the user selects it, it transforms the gallery into a slider.

Or, suppose your theme needed to offer a big hero section with a call-to-action button. There is no need for a custom block in this situation. Theme authors can almost exclusively do this by building a custom pattern with existing blocks.

The solution is not to bundle the block in the theme or create a plugin that only works with that one theme.

The beauty of the block system is that most of the pieces are already in place, and they can be rearranged, grouped, and styled in unlimited ways.

Today, there are hundreds of theme-specific plugins in existence. Part of that is because themers were working around the theme review guidelines. Part of that is because some developers did not think creatively enough about solutions. But, the biggest part of it has been because WordPress has not standardized how to build things across the entire platform. Much of that has changed and will continue to change as full-site editing crosses the horizon in 2021. There will be clear paths for themes and plugins.

However, if theme companies continue building theme-specific blocks, we are just lugging along the baggage that the block system is meant to leave behind.


24 responses to “Do Not Build Theme-Specific Block Plugins for WordPress, Please”

  1. Great article Justin, and I couldn’t agree more for blocks published for others to use.

    I would be curious however, to hear your thoughts on how you think this should work when it comes to custom built solutions. One of the biggest complains I have with Gutenberg when it comes to more complex layouts is separating the page structure from content.

    For simple pages, I make use of most of the core blocks. On more advanced pages however, the homepage being a common one, I find it’s easier to create custom blocks using Advanced Custom Fields for each section/row of the page so the client doesn’t have to worry about the visual/UX side of things.

    I normally batch these blocks into the custom theme I’ve built, which I don’t personally like as I know content would be lost should the client ever change a theme. I always try to explain this to the client before starting work so they’re never caught out.

    My problem is these blocks are often so specific and design heavy that they would probably look odd if used out of context with a different theme. It’s a problem I struggle to find an answer to every time I build a new block.

    I’d love to hear your thoughts on this.


    • Hi I’m not the author, but want to share my intake with your issue.

      Most of the time you only need custom blocks for Pages or whatever your custom post type is. So limit the block to only be selectable in Pages.

      Broken pages when changing theme is a normal and expected thing even before Gutenberg, so you don’t have to worry about that.

      But blog posts should only use built-in blocks so they stay intact.

    • Theoretically you could just have simple “white label” styling for your block plugin and then create a CSS override in the theme for each new project. But I agree, even the functionality for blocks in custom builds is often extremely build-specific. You could try to make the functionality more generic and reusable but then the UI could get more complex as you’re trying to make it more flexible. Which can more for a more complex editing experience for the client. It’s tricky, but worth pursuing.

      Then again in 15 years of building WordPress Themes for clients I have never… not once… had a client change their theme. It’s always a total rebuild. But theoretically it doesn’t have to be that way. And never did have to be that way if all they wanted was a blog. But 99.9% of clients need more than a simple blog that sticks with the standard out-of-the-box WordPress content schema. They want custom page layouts and components that you could just never do before without a whole host of ugly partial workarounds (custom template, widgets, shortcodes, etc.). Block do, theoretically, finally solve this but my gut feeling is that this utopia of simply “re-skinning” a site’s frontend with a theme will never happen. And no one actually cares. It’s a 20 year problem that no one has ever actually cared about. Site rebuilds always have new custom design AND new custom functionality.

    • As someone who has worked in both worlds, I would follow the rules to the extent that it made sense for a specific project but throw out the rulebook otherwise. I don’t want to leave a mess for myself or the next developer if I can help it.

      Custom-built solutions are never going to be the same as plugins/themes built for general, public use.

      With that said, some of the developers I know who do more client work are making more extensive use of patterns and custom templates (for CPTs) today. Of course, many of them are using custom ACF blocks too.

  2. Totally agree with the article, Justin.

    Building a theme-specific blog plugin (or any kind of theme-specific plugin) will flood the with them. They make the theme-plugin separation useless, and thus the presentation-functionality separation useless.

    Instead of building such block plugins, theme authors should try to leverage the available blocks in Gutenberg to do useful things, such as adding block styles.

    I have an useful case of using Gutenberg blocks: we make a small plugin called eRocket that use Gutenberg social blocks to create a contact widget (which shows social profile links) and social sharing buttons. I think it’s better to stand on the shoulder of Gutenberg to build things instead of adding more similar things to it.

  3. This is I believe what happens when theme authors have been in a quandary as to what the future holds for them relative to Gutenberg enabling FSE. For them, the future is not clear. So they would rather create theme specific blocks to lock their customers in.

    Will they create an FSE version of their current themes? Or will they just migrate their existing themes to FSE?

  4. You could also easily add a slider style for the Gallery block. When the user selects it, it transforms the gallery into a slider.

    Can you point me to a tutorial on how to do this, please? Most slider solutions out there use some sort of JS script to work. Can I enqueue scripts when creating a block style?

    • I don’t know of any tutorials offhand. But, here’s a quick solution off the top of my head for the front end:

      add_filter( 'render_block', function( $content, $block ) {
          if ( ! empty( $block['attrs']['className'] ) && false !== strpos( $block['attrs']['className'], 'is-your-style' ) {
              // enqueue scripts      
          return $content;
      }, 10, 2 );

      There may be a better hook than render_block. The best thing is to just dive into the core source code and test things out.

  5. I understand your point of view.

    I’d like to offer our opinion. As a small web agency we are only just discovering the possibilities of Gutenberg, we clamped onto the Classic Editor for a while.

    But since some months we add Gutenberg blocks to our themes, using the features of Advanced Custom Fields. Indeed, this will lock the client into the specific theme. But the sites we build for these cliensts are custom designed for them, and therefore meant for a single purpose. This also means the available custom fields, post-types and taxonomies are specifically added for that client.

    For these clients, to be able to switch themes is not a goal. The custom blocks are also not meant to be used by other users, since they rely on the custom fields, custom post-types and custom taxonomies we added for the specific theme.

    A big discrepancy onto the article, is that we don’t publish our themes, plugins and blocks for general use. They are distributed through Git and GitHub Updater and only available to the specific client. Therefore I guess there can’t be any misunderstandings for other people, because they won’t stumple upon them anyway.

    But, in the end, I share your opinion. I’d like the blocks to be theme and plugin independent, so after years of good use, we can build a new theme for the client and just use the same content (and blocks).

    So thanks for publishing your opinion, we will look into it.

  6. As someone who has used WordPress since 2011, I would like to see a repository of blocks built that could be added individually sort of like we do with plugins. This way we don’t add any unnecessary bloat to the site. Instead of adding a bunch of blocks I don’t need and will never use, I would just add the ones I need. I’m not sure if this is possible because I’m not a developer, but if everyone contributed to one modular system that would be amazing.

    • WordPress already has a repository of one-off blocks. It’s almost a bit of a hidden feature at the moment. However, you can search for and install blocks directly from the block inserter right now. They are pulled from the block directory.

      Eventually, WordPress is planning to add a block management screen that is similar to what we currently have for plugins and themes.

  7. I’m in favour of authors extending existing core blocks – it’s when the block doesn’t exist initially that the problems starts (and then everyone writes accordion or tab or map blocks and puts them into block libraries with 30 more you never wanted…).

    I’d like to see any theme author who writes a block adding the basic elements of that block as a separate block/plugin for all to use, then using their theme to extend it the way they want. That way you only lose the theme-specific extensions and styling if you deactivate the theme, not the whole block (which would presumably default to a Paragraph?)

  8. I would prefer to see blocks and the block editor revert to being an optional plugin you install if you want that type of editor. I darn sure don’t want blocks in my sidebar. Guess it’s time to ditch WordPress because they literally don’t care about it listen to their long-time users who think these new blocks are terrible. The block editor was a huge step backwards and frankly, I’m ashamed that I ever wanted to be a WordPress developer.

  9. The point you touch on is the allure of the other page builders like Divi and Elementor.

    All of the advanced blocks come with it and there is a standardized “divi way” and “elementor way” of doing things. Until wordpress standardizes gutenberg it will continue to be a mish-mash of semi-compatible pieces.

  10. I agree with you, although I’m not sure I understand what will make widgets unnecessary unless you drive then into the theme (please, no). I still want “universal blocks” that show on all pages or some definable subset of pages, without having to embed those blocks in every page.
    I’m open to a different solution, just don’t see it here…
    Of course, that was not your main point, which you made well.

  11. Our agency builds wordpress websites using 100% custom built wordpress themes based on underscores but using Bootstrap 4 as our framework. Bootstrap offers the flexibility we need to quickly build bespoke designs.

    We used to build our sites using ACF flex content blocks, but now are using ACF’s Gutenberg blocks.

    Because of the way we prefer to build our sites in modular sections, we cant allow our clients to use any core blocks except those we explicitly define to work in gutenblocks we have setup that use innerblocks. Otherwise they wouldnt be contained in bootstraps container>row>grid markup and would break the layout of the website.

    As an agency we need absolute and total control over the markup of our websites. Gutenberg is a threat to that total control and would allow clients to build layouts that are outside of the brand standards.

    I think there is a huge division between regular people who build janky websites and would be totally fine with getting an off the shelf theme, and just adding whatever blocks they need – vs Agencies and companies who need total control over the design.

  12. As an end user, I find blocks cumbersome. I really don’t see the point in complicating blog posts – which is really the only aspect of my site that I’m adding to regularly.

    For other pages (home, contact, etc) I see nothing wrong with theme specific blocks or templates. Yes if I change themes I might have to fix a few pages, but if I’m changing themes I’m probably going to restructure my site anyway (otherwise why bother with a redesign).


Subscribe Via Email

Enter your email address to subscribe to this blog and receive notifications of new posts by email.

%d bloggers like this: