Introducing the Breadcrumbs WordPress Block Plugin

In 2009, I announced the release of my first breadcrumbs plugin. It was a one-file PHP script that I’d been using in my themes for around a year, and I wanted to contribute it to the larger WordPress community in the form of a plugin. Over the past 14 years, this original script has changed multiple times.

Today, I am happy to announce a new version of it. This time as a block plugin: X3P0: Breadcrumbs.

I submitted it to the official WordPress plugin directory last week, and it should eventually make it there. There’s currently around a two-month waiting period for plugin reviews, and I wanted to get this into the community’s hands a bit sooner than that. You can snag a copy from the Releases page on the plugin’s GitHub repository.

The goal for this block was to offer a simple interface that anyone could use instead of having to interact with a complex PHP script. 

Aside from the standard design tools (e.g., colors, dimensions, border, etc.), the block offers a handful of custom options in version 1.0. The first is the ability to customize how the home “crumb” works:

WordPress Site Editor with a breadcrumbs block highlighted. Overlaying the canvas is a icon picker for a home icon.

The icon picker lets you choose from a range of home icons and emoji. You can also show/hide the “Home” label.

Next to it in the toolbar is a separator picker, which lets you choose the icon or symbol that sits between each breadcrumb:

WordPress Site Editor with a breadcrumbs block highlighted. Overlaying the canvas is a icon picker for a separator icon.

The block boasts a couple of extra options for conditionally hiding the breadcrumbs on the site homepage and whether the last breadcrumb item should be visible.

I’d love for you to give the plugin a spin and let me know what you think. There are many ways that I believe the plugin could be even better, but I’d rather get your feedback first.

A Few Questions and Answers

Why does the editor show placeholder breadcrumbs?

One early version of this block did dynamically populate the breadcrumbs in the Post Editor. But this block is primarily meant to be used in templates in the Site Editor. Like other template-specific blocks, there’s no way to populate the data (which is dynamic) until the block is rendered on the front end. So placeholders make sense.

I opted to keep the output the same between the Post Editor and Site Editor so that the experience would be consistent regardless of where the block was inserted. Plus, this keeps the code lighter, which is always a win in my book.

Does this work with classic themes?

Absolutely. The block is just a wrapper around a PHP class, and you can call it directly from your classic theme’s PHP templates:

<?php if ( class_exists( 'X3P0\Breadcrumbs\Trail' ) ) {
} ?>Code language: PHP (php)

Alternatively, you can parse and output the block:

<?php echo do_blocks( '<!-- wp:x3p0/breadcrumbs /-->' ); ?>Code language: PHP (php)

Why aren’t there more block settings?

The PHP under the hood of the plugin is highly configurable. There’s around two dozen options and a few filter hooks that allow developers to change how nearly every aspect of the breadcrumb trail is output.

But just dumping each of those options into the interface would likely make a terrible user experience.

For version 1.0, at least, I took the less is more approach to block settings. This will give me time to both listen to feedback on what’s actually needed and to evaluate how those options would be best integrated into the UI in the future.

Does the plugin handle X, Y, or Z scenarios?


Breadcrumb trail structures can range from fairly simple to extremely complex. The plugin tries to handle each scenario it comes across as gracefully as possible by default.

Again, as I introduce more of the plugin settings from the PHP side into the block itself, this will open it up for more editor-based customization.

What about the potential core breadcrumbs block?

There is a three-year-old ticket requesting a breadcrumbs block in core WordPress, and there is also some early work in a pull request. I feel like we’ll eventually have a core block, but there is no guarantee on when that will happen.

A core block could take a while since it would need to consider extensibility before becoming a feature-complete implementation. There are several breadcrumb solutions, and each have their own take on what the resulting output should be.

If/When it happens, I’ll reevaluate what this means for this plugin. It may be better to migrate it as a variation on the core block or for it to continue being a standalone implementation. As they say, I’ll cross that bridge when I come to it.

I’m also happy for core to borrow any (or all) code needed from my plugin—the great thing about the GPL is that we can do cool things like share code.


We take it for granted over the years, but this block in core would be a nice little trick. Please let there be a custom icon feature to let us upload our own SVG in the mix !

I’ll put some more focus on custom icons in a future release. For now, there are two filter hooks available for adding custom icons.

This looks great! Some great features. I like that it is minimal yet just enough options to be very versatile. I love these smaller, specific use block plugins, especially ones that enhance the template building experience.

Have you seen the Breadcrumb Block plugin? It’s nice to have some plugin options that do the same thing.

Yes, I ran across it the other day. The PHP part is partially adapted from of a very old version of this plugin’s PHP. I’d like to reach out to the author to see if they’d be willing to update to a more recent codebase. There’s plenty of room in the repo for different approaches to the block itself, even if they share the same underlying PHP library.