PHPackages                             themehybrid/hybrid-breadcrumbs - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. themehybrid/hybrid-breadcrumbs

ActiveLibrary

themehybrid/hybrid-breadcrumbs
==============================

A powerful breadcrumb script for inclusion with WordPress themes.

1.0.1(7y ago)45633[2 issues](https://github.com/themehybrid/hybrid-breadcrumbs/issues)[1 PRs](https://github.com/themehybrid/hybrid-breadcrumbs/pulls)GPL-2.0-or-laterPHPPHP >=5.6

Since Sep 14Pushed 1y ago8 watchersCompare

[ Source](https://github.com/themehybrid/hybrid-breadcrumbs)[ Packagist](https://packagist.org/packages/themehybrid/hybrid-breadcrumbs)[ Docs](https://github.com/justintadlock/hybrid-breadcrumbs)[ RSS](/packages/themehybrid-hybrid-breadcrumbs/feed)WikiDiscussions master Synced today

READMEChangelogDependenciesVersions (5)Used By (0)

Hybrid\\Breadcrumbs
===================

[](#hybridbreadcrumbs)

Hybrid Breadcrumbs is a drop-in package that theme authors can use to add breadcrumbs to their WordPress themes.

The package is a developer-friendly project that aims to take out all the work of handling breadcrumbs. It is one of the most advanced and robust breadcrumb systems available that can handle nearly any setup to show the most accurate breadcrumbs for each page.

This project was [originally launched in 2009](http://justintadlock.com/archives/2009/04/05/breadcrumb-trail-wordpress-plugin) as the Breadcrumb Trail plugin. Hybrid Breadcrumbs is a reimagining of that original script as a better drop-in package for theme authors to use.

Requirements
------------

[](#requirements)

- WordPress 4.9+.
- PHP 5.6+ (preferably 7+).
- [Composer](https://getcomposer.org/) for managing PHP dependencies.

Documentation
-------------

[](#documentation)

The following docs are written with theme authors in mind because that'll be the most common use case. If including in a plugin, it shouldn't be much different.

### Installation

[](#installation)

First, you'll need to open your command line tool and change directories to your theme folder.

```
cd path/to/wp-content/themes/
```

Then, use Composer to install the package.

```
composer require justintadlock/hybrid-breadcrumbs
```

Assuming you're not already including the Composer autoload file for your theme and are shipping this as part of your theme package, you'll want something like the following bit of code in your theme's `functions.php` to autoload this package (and any others).

The Composer autoload file will automatically load up Hybrid Breadcrumbs for you and make its code available for you to use.

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

### Translations

[](#translations)

Because this script has a few internationalized text strings within it, you'll want to overwrite the textdomain or use something like this [one theme with two textdomains trick](https://gist.github.com/justintadlock/7a605c29ae26c80878d0) (the textdomain in this project is `'hybrid-core'`).

If you're creating a theme using the [Hybrid Core framework](https://github.com/justintadlock/hybrid-core), you don't have to worry about this. Hybrid Core will appropriately handle translations for you.

### Usage

[](#usage)

Most developers will want to utilize the `Hybrid\Breadrumbs\Trail` class. It is a static wrapper class that essentially acts as *syntactic sugar* for use in theme templates.

Typically, a call like the following would go into your theme's `header.php` template but can be used anywhere you want to show the breadcrumb trail.

```
Hybrid\Breadcrumbs\Trail::display();
```

*Note that the plugin's namespace is `Hybrid\Breadcrumbs`. If you're working within another namespace, you'll want to add a `use` statement after your own namespace call or call `\Hybrid\Breadcrumbs\Trail::display()` directly. I'll assume you know what you're doing if you're working with namespaces. Otherwise, stick to the above.*

### Static class

[](#static-class)

The `Hybrid\Breadcrumbs\Trail` class has the following methods:

```
// Returns a new instance of the Hybrid\Breadcrumbs\Breadcrumbs class.
Trail::breadcrumbs( array $args = [] );

// Makes a breadcrumb trail and returns an instance of the Hybrid\Breadcrumbs\Breadcrumbs.
Trail::make( array $args = [] );

// Returns an array of Hybrid\Breadcrumbs\Crumb\* objects.
Trail::all( array $args = [] );

// Displays the HTML output of the breadcrumb trail if it exists.
Trail::display( array $args = [] );

// Returns the HTML output of the breadcrumb trail or an empty string.
Trail::render( array $args = [] );
```

### Breadcrumbs class

[](#breadcrumbs-class)

If you don't care for static classes and need to work directly with the object, that's fine too. You can create and use a the `Breadcrumbs` object like so:

```
// Create a new Breadcrumbs object.
$trail = new \Hybrid\Breadcrumbs\Breadcrumbs( array $args = [] );

// Makes the breadcrumb trail and returns an instance of the object.
$trail->make();

// Returns an array of Hybrid\Breadcrumbs\Crumb\* objects.
$trail->all();

// Displays the HTML output of the breadcrumb trail if it exists.
$trail->display();

// Returns the HTML output of the breadcrumb trail or an empty string.
$trail->render();
```

### Parameters

[](#parameters)

The `Breadcrumbs` class and the `Trail` class methods all accept a single parameter, which an array of optional arguments for setting up the breadcrumb trail. The following is a list of all the available options (see below for defaults).

- `labels` - An array of labels.
- `post_taxonomy` - An array of taxonomies to show for single posts based on post type.
- `show_on_front` - Whether to show the breadcrumb trail on the site front page.
- `show_trail_end` - Whether to display the final breadcrumb.
- `network` - Whether to include the main site at the beginning of the trail on multisite.
- `before` - HTML to display before.
- `after` - HTML to display after.
- `container_tag` - HTML tag to use for the container.
- `title_tag` - HTML tag to use for the title.
- `list_tag` - HTML tag to use for the list.
- `item_tag` - HTML tag to use for each breadcrumb.
- `container_class` - Class to use for the container.
- `title_class` - Class to use for the title.
- `list_class` - Class to use for the list.
- `item_class` - Class to use for each breadcrumb.

#### Default Parameters

[](#default-parameters)

```
$defaults = [
	'labels'          => [],
	'post_taxonomy'   => [],
	'show_on_front'   => false,
	'show_trail_end'  => true,
	'network'         => false,
	'before'          => '',
	'after'           => '',
	'container_tag'   => 'nav',
	'title_tag'       => 'h2',
	'list_tag'        => 'ul',
	'item_tag'        => 'li',
	'container_class' => 'breadcrumbs',
	'title_class'     => 'breadcrumbs__title',
	'list_class'      => 'breadcrumbs__trail',
	'item_class'      => 'breadcrumbs__crumb'
];
```

#### Default Labels

[](#default-labels)

Labels are used for various breadcrumbs where WordPress doesn't provide a title/labels.

```
$defaults = [
	'title'               => __( 'Browse:',                               'hybrid-core' ),
	'aria_label'          => _x( 'Breadcrumbs', 'breadcrumbs aria label', 'hybrid-core' ),
	'home'                => __( 'Home',                                  'hybrid-core' ),
	'error_404'           => __( '404 Not Found',                         'hybrid-core' ),
	'archives'            => __( 'Archives',                              'hybrid-core' ),
	// Translators: %s is the search query.
	'search'              => __( 'Search results for: %s',                'hybrid-core' ),
	// Translators: %s is the page number.
	'paged'               => __( 'Page %s',                               'hybrid-core' ),
	// Translators: %s is the page number.
	'paged_comments'      => __( 'Comment Page %s',                       'hybrid-core' ),
	// Translators: Minute archive title. %s is the minute time format.
	'archive_minute'      => __( 'Minute %s',                             'hybrid-core' ),
	// Translators: Weekly archive title. %s is the week date format.
	'archive_week'        => __( 'Week %s',                               'hybrid-core' ),

	// "%s" is replaced with the translated date/time format.
	'archive_minute_hour' => '%s',
	'archive_hour'        => '%s',
	'archive_day'         => '%s',
	'archive_month'       => '%s',
	'archive_year'        => '%s',
];
```

#### Default Post Taxonomies

[](#default-post-taxonomies)

By default, no post taxonomies are registered. However, if a site's post permalink structure is set to only `%postname%`, the following will be the default.

```
$defaults = [
	'post' => 'category'
];
```

Copyright and License
---------------------

[](#copyright-and-license)

This project is licensed under the [GNU GPL](http://www.gnu.org/licenses/old-licenses/gpl-2.0.html), version 2 or later.

2018-2019 © [Justin Tadlock](http://justintadlock.com).

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance27

Infrequent updates — may be unmaintained

Popularity21

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity60

Established project with proven stability

 Bus Factor1

Top contributor holds 98.1% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~89 days

Total

4

Last Release

2525d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/ef868a4b45ef0263f49361744b8bb04e8f3cfcb8f3f79b274fc62823115ee596?d=identicon)[justintadlock](/maintainers/justintadlock)

---

Top Contributors

[![justintadlock](https://avatars.githubusercontent.com/u/1816309?v=4)](https://github.com/justintadlock "justintadlock (52 commits)")[![mrxkon](https://avatars.githubusercontent.com/u/22611066?v=4)](https://github.com/mrxkon "mrxkon (1 commits)")

---

Tags

wordpress

### Embed Badge

![Health badge](/badges/themehybrid-hybrid-breadcrumbs/health.svg)

```
[![Health](https://phpackages.com/badges/themehybrid-hybrid-breadcrumbs/health.svg)](https://phpackages.com/packages/themehybrid-hybrid-breadcrumbs)
```

###  Alternatives

[roots/wordpress

WordPress is open source software you can use to create a beautiful website, blog, or app.

19116.9M257](/packages/roots-wordpress)[aristath/kirki

Extending the WordPress customizer

1.3k73.0k4](/packages/aristath-kirki)[wpreadme2markdown/wpreadme2markdown

Convert WordPress Plugin readme.txt to Markdown

9564.6k4](/packages/wpreadme2markdown-wpreadme2markdown)[wpstarter/framework

The WpStarter Framework - Laravel Framework for WordPress

1810.1k4](/packages/wpstarter-framework)[tacowordpress/tacowordpress

WordPress custom post types that feel like CRUD models

232.2k](/packages/tacowordpress-tacowordpress)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)