Using the Breadcrumb Trail Block

Since version 6.3.0, Breadcrumb NavXT has shipped with a built in Gutenberg Block. In Breadcrumb NavXT version 7.3.0 the Breadcrumb Trail block was rewritten to have feature parity with the Widget. The Breadcrumb Trail block allows you to place a breadcrumb trail in your theme without touching any of your theme’s files. Since Breadcrumb NavXT has a two different display functions (bcn_display() and bcn_display_list()), along with three input variables for these functions ($return, $linked, $reverse), the block has a few settings available to the user.

Currently, the following settings are available:

  • Whether to output the trail as a list or not. If checked, the output trail will be placed in an unordered list, with each breadcrumb belonging to its own list element.
  • Whether to link the breadcrumbs or not. If checked (default), each of the breadcrumbs in the breadcrumb trail will have a hyperlink.
  • Whether to reverse the order of the trail or not. If checked, the breadcrumb trail will be output in reverse order (the leftmost breadcrumb (or first breadcrumb in a list output) will be the breadcrumb for current page).
  • Whether to hide the trail on the front page or not. If checked, the breadcrumb trail for the front page of your site will not be displayed (e.g. when is_front_page() evaluates to true).

The block still uses the settings values specified in the Breadcrumb NavXT settings page to define its behavior while filling the breadcrumb trail.


This filter is applied within the bcn_breadcrumb_trail class in the display_loop() function just before assembling the breadcrumb string. This filter was introduced in version 7.2. It receives four parameters:

  • $separator(string)(required) The separator to place after the current breadcrumb.
  • $position(integer)(optional) The current breadcrumb position at the current depth in the breadcrumb trail
  • $last_position(integer)(optional) The last possible position at this depth of the breadcrumb trail (size of the breadcrumb trail at this depth)
  • $depth(integer)(optional) The current depth (dimension/level) within the breadcrumb trail

Related Articles


This filter is applied within the bcn_breadcrumb_trail class in the display_loop() function at the beginning of the function. This filter was introduced in version 7.1. It receives one parameter:

  • $breadcrumbs(array)(required) The array of bcn_breadcrumb objects that comprise the breadcrumb trail.


This filter is applied within the mtekk\adminKit\adminKit class in the opts_update() function just before saving the settings to the option entry. This filter was introduced in version 7.0. It receives one parameter:

  • $settings_diff(array)(required) The array of non-default valued mtekk\adminKit\setting objects which will be saved to the option entry.

Non-Hierarchical Taxonomies and JSON-LD Compatibility

While Breadcrumb NavXT for some time has provided methods for generating JSON-LD formatted BreadcrumbLists, the use of non-hierarchical taxonomies within a breadcrumb trail may result in non-compliant breadcrumb trails. For the case of a post only being a member of a single term within a non-hierarchical taxonomy, since Breadcrumb NavXT 6.4, compliant JSON-LD is generated. However, when a post is a member of multiple non-hierarchical terms within the same taxonomy, we run into problems.

When using the normal display functions, all of the terms in the non-hierarchical taxonomy that the post is a member of will be displayed, separated by commas. This behavior has been more-or-less the same since support for tags was added in 2.1.0. In essence, when there are multiple terms, there is a second dimension to the breadcrumb trail for that specific breadcrumb.

Unfortunately, it does not appear that BreadcrumbList has the facility to support multi-dimensional breadcrumbs. Hence, a single term needs to be selected when there are multiple for a post. Luckily, the bcn_post_terms filter can be used to do this.

The Code

Introduced in Breadcrumb NavXT 5.4, bcn_post_terms allows us to filter out all of the terms returned by post_terms(). In this case, only the first term is wanted.

add_filter('bcn_post_terms','my_bcn_post_term_selector', 10, 3);
function my_bcn_post_term_selector($terms, $taxonomy, $id)
	//Check to ensure the terms list is an array and there is more than one item in it
	if(is_array($terms) and count($terms) > 1)
		//Return the fist item in a new array
		return array(0 => reset($terms));
	return $terms;

To get started quickly, just copy and paste the above code into a site specific plugin and start playing.

Note: This code relies on behavior introduced in Breadcrumb NavXT 6.4 and will not work in prior versions.

-John Havlik