WordPress Plugin Authors Should Avoid Confusing Users When Naming Blocks

On May 4, the StudioPress development team made a small but significant user-facing change to its Atomic Blocks plugin (now rebranded to Genesis Blocks). It removed the “AB” branding from its block titles. This minor update changed block titles such as AB Accordion and AB Button to Accordion and Button, respectively. On the surface, this change probably seemed of little consequence to the developers on the project. However, for at least one user, it created a massive workload.

Unless users religiously followed the GitHub code commits, they would have missed this update. Stacked with several other code changes for a seemingly unrelated ticket, the team left a message that read, “Remove unnecessary ‘AB’ from block titles.”

The change made it into version 2.8.2 of the plugin, which launched a day later.

The problem was that there was no message in the change log that noted this. Users had no indication that the blocks from the plugin were being renamed. Typically, this would not be a big deal since the plugin team had merely dropped the “AB” prefix from the otherwise unchanged titles. However, what happens when one of those blocks’ titles matches a core block title?

That was the issue that Marcus Tibesar ran into. The AB Button block suddenly became the Button block. Thinking he was using the core WordPress Button, he made liberal use of it throughout his site. Throw in his decision to drop the plugin after StudioPress rebranded its plugin to Genesis Blocks, it became a bit of a disaster to clean up.

“I have been using the Button block for months now only to discover that I’m actually using the Atomic Blocks button block!” wrote Tibesar in a comment on the Atomic Blocks rebranding post.

Theoretically, he should have needed to update only any lingering blocks from Atomic Blocks that he had knowingly used. But, he was stuck with blocks that he had unknowingly added to his posts and pages through no fault of his own.

This particular scenario was made worse because WordPress 5.4, released on March 31, introduced a new Buttons (plural) block. The old single Button block was removed from the normal inserter. While not all block-naming issues are so convoluted, it still begs the question: how can plugin authors avoid causing these types of user-experience issues?

It is easy to throw blame toward StudioPress — and the team could perhaps use a scolding for not being clear about the change when it happened. However, this brings forth a couple of things the greater WordPress community needs to figure out. The first is whether plugin authors need to use a consistent, prefixed naming scheme for their blocks. The second is what can WordPress do to help mitigate issues.

Prefix All the Things

Screenshot of adding button blocks from multiple plugins to the editor.
Buttons, buttons, and more buttons.

That is the common saying in the WordPress development world, right? Prefixing and namespacing guidelines generally apply to the actual code, which is where conflicts arise. However, there are times when prefixing public-facing text is warranted.

And those times are when plugins utilize a shared space.

The block editor is one such shared space. With more and more block plugins landing in the directory, it is time that plugin authors consider how block-naming schemes affect end-users. The issue is certainly not limited to Atomic/Genesis Blocks. This has been an ongoing trend with several block library plugins. Some do better than others, but it’s a toss-up each time a user installs such a plugin.

The easiest route is for plugin authors to simply prefix all custom blocks with their company branding (e.g., AB Button). On the other hand, not every block shares a title with one of the core blocks. For example, a block titled Product Carousel may not need to distinguish itself further from other blocks. It is unlikely that end-users are running multiple eCommerce plugins with blocks that share the same title.

“All, repeat all, should have a prefix,” said Tibesar. “The prefixes eliminate any confusion as to whether we users are selecting a core block or a third-party block. The most popular plugins appear at the top of the list, and it’s confusing from whence they came when prefixes are absent.”

At the very least, third-party blocks should have a prefix if their titles match one of the core blocks. End-users should not see two different Cover blocks in the block inserter, for example. Instead, they should see the core Cover and a second, uniquely-titled block. Prefixing is an easy way to do that. But, I could live with anything that does not cause user confusion.

Locating Instances of Block Usage

Screenshot of the Manage Blocks screen prototype for WordPress.
Manage Blocks screen.

In late 2019, the Gutenberg team released the first prototype of a potential block management area for the WordPress admin. The Manage Blocks screen from the prototype showcased an area that would allow users to manage every block on their site. One of the more important bits of information on this screen was an “Instances” count, which displayed the number of times a block was in use. It further linked to a screen with every post that had a particular block.

One of the reasons this feature is important is that it would allow end-users to locate posts that they may want to clean up. Using the Atomic/Genesis Button block as an example, Tibesar could track down all those old uses and make any changes he wanted.

He said he would absolutely welcome this feature in WordPress. “New users are tempted to load up on zillions of block plugins all to be forgotten later. Also, maintainers would use this tool when cleaning up broken sites. Just being able to see an overview of what blocks were used where, will allow publishers to dial back the number of block plugins installed on their sites, especially when new plugins and technologies emerge.”

Because this feature is not in core yet, he had to turn to the Find My Blocks plugin, which helped him identify 22 posts and pages where he had unknowingly used the Button block from Atomic/Genesis Blocks. In the long term, this is something that needs to be handled directly in WordPress. It is unlikely to be the last time a user needs to clean house and get rid of old blocks.


15 responses to “WordPress Plugin Authors Should Avoid Confusing Users When Naming Blocks”

  1. Hey folks,

    I just wanted to address a few points here. Firstly, I want to apologize for anyone confused by the removal of the AB prefixes from the block names. I’m genuinely bummed when anyone has a bad experience with one of our products. This wasn’t done to prioritize our blocks over core blocks or any other 3rd party blocks. Quite the opposite, in fact. We believe the WordPress editor belongs to everyone, and the trend of over-branding and having logos and product names on blocks, sidebars, and admin bars can be distracting and take away from the core editing experience.

    Removing the AB prefix from each block was part of a larger effort of updating and improving the blocks in preparation for a rename to Genesis Blocks, as covered in the original Tavern article. Furthermore, we’re actively vetting our blocks and considering deprecating blocks that provide unnecessary competition to core blocks, such as the button block. No need to reinvent the wheel!

    As one of the first block plugins on the repo, we’ve been learning and growing the block ecosystem on the bleeding edge, and that comes with all kinds of fun surprises. One of which is the lack of standards and practices. We join the call for well-defined standards that all blocks can implement to give WordPress users a consistent experience.

    • Thanks for chiming in, Mike. Creating a user experience that works for everyone is tough. We obviously have the benefit of hindsight in this particular situation, but it’s an important thing to discuss while blocks are still relatively young.

      After giving some more thought to this over the past day, I have been wondering of core WP could potentially add some sort of indicator within the UI that would help distinguish core from third-party blocks. Your team is a bit more in the thick of block dev, so it’d be great to see if y’all had any ideas for this or just creating a standard to follow. I’m cautious about prefixing always being the best idea because of the limited space.

    • << we’re actively vetting our blocks and considering deprecating blocks that provide unnecessary competition to core blocks, such as the button block. No need to reinvent the wheel! >>

      It has taken me a few weeks, but I’ve removed all the (Atomic Blocks) Button blocks from my site.

      Mike, no matter the explanation, adopting the core block name ‘Button’ and not telling your plugin users was just plain wrong. Apology accepted.

  2. Blocks should carry an author label, without doubt. Navigating and inserting is cumbersome enough without having the added confusion of blocks with identical names. Lacking clear identifiers it’ll be way too easy to turn the inserter into an absolute shitshow. In my own experience I try to avoid third party blocks unless absolutely necessary an example of why being a recently installed plugin which I used for a quick fix to get a specific gallery feature. It only contained 3 blocks, upon subsequent updates this has now ballooned to 38, yes thirty eight along with an obscene amount of options which slowed the editor too a crawl. I decided to bite the bullet and implemented the feature using ACF so I could again dump the third party block. Still, there are notable examples of excellent blocks such as https://wordpress.org/plugins/accordion-blocks/ simple, clear, un-opinionated styling and it does exactly what is says on the tin.

  3. Wasn’t there a time, when 3.party Blocks, were clearly listed under a brand heading, like, all Atomic Blocks in Atomic Block section in the inserter? I miss that. Its super confusing with 3 different button blocks all named “Button”

    Being using Gutenberg a lot the last year, I really really long for some sort of block management, including:
    – core management of block access rights, let the authors use a specific set of blocks only.
    – graceful fallback once a 3rd party block plugin is disabled.
    – a list / search feature to find out where a block is used.
    – maybe even a requirement for block plugin developers to make their blocks optional defaulting to disabled.

    I cannot unleash my co-authors with Gutenberg until proper management is in place, I would spend too much time cleaning up after the mess they will make.

    • Yes, most block collection plugins I’ve seen categorize all their blocks in the inserter. They may also add them to other categories there too. But, the categorization doesn’t appear if you’re doing slash commands, such as /button. The first option there may not be the core one. In the screenshot used in the post, I believe the core Buttons block is actually at the bottom of the list.

  4. Agree this is also an area where we could do a better job presenting where a block comes from in some of the inserting UIs. There are also some tickets to improve the search experience for direct matches and priorities. For some plugins that have extreme 1:1 overlapping, it might also make sense for them to unregister a core block like Buttons when providing their own.

    • I’d definitely like to see better direct matching. I often do the slash command for /image, and the core Image block in that scenario is down the list of other image-related blocks from third-party plugins. It’s super irritating. Well, really it’s one of those small annoyances that I have learned to live with.

  5. I like everything of StudioPress. Genesis framework is the best ever for bloggers. Automic blog is a simple Gutenburg block-based plugin. I am using this simple plugin one of my WordPress blogs. However, I agree with this blog post. The plugin author should consider the rename of the blocks.


Subscribe Via Email

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

%d bloggers like this: