Hybrid Breadcrumbs: A reusable script for everyone

For years, I’ve had a breadcrumbs script that I’ve maintained as both a theme drop-in library and as a separate plugin. Today, I’m officially announcing the next evolution of that script that will make it more useful for WordPress developers.

I’ve created a new repository for the Hybrid Breadcrumbs project. It can now be used with any theme or even be the foundation of other breadcrumb plugins.

I’ve been promoting it as an add-on project for the Mythic starter theme, but it’s a standalone project that anyone can use. It has no dependencies on other code (other than WordPress, of course).

This post is going to serve as both an introduction and quick, getting-started tutorial.

Quick history

When I first got into serious WordPress theme development, I realized how few options there were for good breadcrumb solutions. That led me to eventually build my own system to package with themes, which was eventually released in 2009 as the original Breadcrumb Trail plugin.

Over the years, I’ve maintained the code between my themes via the Hybrid Core framework and the Breadcrumb Trail plugin. This was tedious and unnecessary work maintaining the code bases across projects.

This year, I overhauled all of the code and have released it as a Composer package where theme/plugin authors can plug it into their projects when needed.

What does the package do?

It creates a list of links (breadcrumbs) from the currently-viewed page up each level until it reaches the home page.

Unlike many other breadcrumb solutions, the script closely follows how your site’s permalinks (rewrite rules) are set up. It handles custom post types, taxonomies, and all sorts of scenarios that are not default to WordPress. And, it’ll handle most of these situations without any configuration.

Of course, no breadcrumbs script can cover 100% of all scenarios perfectly, depending on how far from native WP you go. And, some folks just want their breadcrumbs to do something different. Everything can be changed.

Hybrid Breadcrumbs is an object-oriented approach to handling breadcrumbs. I built it so that developers could change things to suit their project’s needs.

Installing Hybrid Breadcrumbs

The following is from the perspective of theme dev, but plugin dev should be pretty similar.

The package requires the following:

To install, navigate to your theme folder via your command line utility and type the following command.

composer require justintadlock/hybrid-breadcrumbs

If not already using Composer, drop the following in your functions.php file or a more appropriate place.

if ( file_exists( get_parent_theme_file_path( 'vendor/autoload.php' ) ) ) {
    require_once( get_parent_theme_file_path( 'vendor/autoload.php' ) );

That will make sure that the project’s classes get loaded when called.

Displaying breadcrumbs in a theme

The package provides a static class, which is essentially syntactic sugar, for quickly outputting breadcrumb trails in the themes. For most theme authors, this is all you’ll ever need.

Open your theme’s header.php template or another template where you want the breadcrumbs to appear. For example, if using the Mythic starter theme, you’d open resources/views/header/default.php. Add the following code.

<?php Hybrid\Breadcrumbs\Trail::display() ?>

That’s it. Your breadcrumbs will appear. You merely have to style them from that point.

There are quite a few configuration options available. These are all covered in the readme.md file. You can do things like:

  • Change whether breadcrumbs show on the front page.
  • Alter the HTML tags used.
  • Use custom classes (follows a BEM-style naming scheme by default).
  • Create custom text labels.
  • Choose to show a certain taxonomy for specific post types.
  • And more.

You can even work directly with the Hybrid\Breadcrumbs\Breadcrumbs object if you prefer objects over a static classes. There are plenty of hooks available for altering things on the fly as well.

Please enjoy

I hope you all enjoy this release. I tried to make it flexible enough so that anyone could use it in their projects.

For those of you wondering about the fate of the Breadcrumb Trail plugin, it will actually get converted over to using this project’s code base. And, the upkeep will be far easier because the code will be maintained from a single source.