WordPress 7.0 finally dropped the native Breadcrumbs block, and honestly, it’s about time. While it looks straightforward in the Site Editor, anyone who has managed a high-traffic WooCommerce store or a complex multisite network knows that “automatic” hierarchy usually breaks the moment you hit custom taxonomies. Fortunately, the core team included two surgical Breadcrumb block filters that give us back the control we need.
I’ve lost count of how many times I’ve had to hack together breadcrumb trails using transients or heavy custom functions because the theme’s logic couldn’t handle “Primary Categories.” Furthermore, with these new hooks, we can finally treat breadcrumbs as data rather than just a string of HTML. Consequently, it makes our templates much cleaner and more maintainable.
Refining Output with block_core_breadcrumbs_items
This is the filter you’ll use for 90% of your UI tweaks. Specifically, it allows you to modify the final array of items just before they are rendered to the screen. Each item in the $breadcrumb_items array expects a label, an optional url, and a security flag called allow_html.
One common “gotcha” I’ve seen is forgetting that allow_html defaults to false. If you try to inject an icon or a span without setting this to true, WordPress will run esc_html() on your input and break the layout. Therefore, always verify your sanitization requirements before shipping.
add_filter( 'block_core_breadcrumbs_items', 'bbioon_inject_custom_shop_root' );
/**
* Injects a 'Shop' link at the start of the breadcrumb trail.
*
* @param array $breadcrumb_items Existing breadcrumb items.
* @return array Modified items.
*/
function bbioon_inject_custom_shop_root( $breadcrumb_items ) {
if ( is_post_type_archive( 'product' ) || is_singular( 'product' ) ) {
array_unshift( $breadcrumb_items, array(
'label' => __( 'Store Front', 'bbioon' ),
'url' => home_url( '/shop/' ),
'allow_html' => false,
) );
}
return $breadcrumb_items;
}The Logic Filter: block_core_breadcrumbs_post_type_settings
This is where the real architectural heavy lifting happens. When a post has multiple taxonomies (like categories and tags) or a product is assigned to five different terms, the block needs to know which path to prefer. This Breadcrumb block filters hook lets you define that preference programmatically based on the post ID or post type.
I recently dealt with a client site where posts were assigned to both “News” and “Featured” categories. The default breadcrumb kept picking “Featured” because of alphabetical sorting, which ruined their SEO silos. By using this filter, we forced the hierarchy to always favor the primary category.
add_filter( 'block_core_breadcrumbs_post_type_settings', 'bbioon_force_primary_taxonomy', 10, 3 );
/**
* Forces the breadcrumb trail to prefer a specific term.
*
* @param array $settings Empty default settings.
* @param string $post_type The current post type slug.
* @param int $post_id The current post ID.
* @return array Modified settings with 'taxonomy' and 'term' keys.
*/
function bbioon_force_primary_taxonomy( $settings, $post_type, $post_id ) {
if ( 'post' === $post_type ) {
$settings['taxonomy'] = 'category';
// You could pull a "Primary Category" from Yoast or RankMath here
$settings['term'] = 'industry-news';
}
return $settings;
}If you’re already familiar with extending WordPress navigation blocks, you’ll find these filters follow a similar pattern. However, the fallback behavior is the real safety net here: if your preferred term doesn’t exist, it simply reverts to the first available term instead of returning an empty trail.
Look, if this Breadcrumb block filters stuff is eating up your dev hours, let me handle it. I’ve been wrestling with WordPress since the 4.x days.
Final Takeaway for Production Sites
The native Breadcrumbs block is a massive win for performance since it removes the need for third-party plugins. But don’t just drop it in and walk away. Use these filters to ensure your site’s UX matches your SEO strategy. For more details, you can dive into the official GitHub PR or the WordPress 7.0 dev notes. Stick to these hooks, and you won’t have to worry about your navigation breaking on the next core update.
