Breadcrumbs: Add filter for preferred taxonomy and term per post type #73283

ntsekouras · 2025-11-14T11:50:18Z

What?

Part of: #72649

Add a PHP filter for users to set their preferred main taxonomy and term per post type. This is needed to have control over the breadcrumbs trail in case a post has multiple taxonomies and/or terms assigned.

This PR Introduces the block_core_breadcrumbs_post_type_settings PHP filter to allow developers to specify which taxonomy and term should be used in breadcrumbs when a post has multiple taxonomies or terms assigned.

Parameters: $post_type (string): The post type slug
Returns: (array) Settings array with the following keys:

taxonomy (string)
term (string)

Fallback behavior:

If the preferred taxonomy doesn't exist or has no terms assigned, fall back to the first available taxonomy with terms assigned.
If the preferred term doesn't exist or isn't assigned to the post, fall back to the first term
If the post has only one term, that term is used regardless of setting

Example

  add_filter(
  'block_core_breadcrumbs_post_type_settings', function(
   $settings, $post_type ) {
      if ( $post_type === 'post' ) {
          $settings['taxonomy'] = 'category';
          $settings['term'] = 'news';
      }
      return $settings;
  }, 10, 2 );

Testing Instructions

Enable GB experimental blocks.
For easier testing I'm adding this plugin and the core block in theme's header and test various cases in the front end.
Add the PHP filter and test various cases. See below for test snippet.

add_filter( 'block_core_breadcrumbs_post_type_settings', 'my_breadcrumb_settings', 10, 2 );

function my_breadcrumb_settings( $settings, $post_type ) {
  if ( $post_type === 'post' ) {
       $settings['taxonomy'] = 'category';
       $settings['term'] = 'news';
  }
  if ( $post_type === 'product' ) {
      $settings['taxonomy'] = 'product_tag';
      //   $settings['term'] = 'rigotag';
  }
  return $settings;
}

You can create your own taxonomies/terms to test, but specifically for the above snippet you'll need:

For the `post` post type

Create a couple of categories and assign them to a post. Replace $settings['term'] = 'news'; with one of your created categories slug. See the front end.

For the `product` post type from Woo

Create a product with a category and one product_tag.
Test that the trail shows the tag.

Screenshots or screencast

Below I'm sharing some screenshots in a site that I've added x3p0-breadcrumbs plugin and the core block in the main header.
Above is x3p0-breadcrumbs and below is the core block.

Preferred taxonomy `product_tag` for Woo products

Preferred term `phones` for posts

github-actions · 2025-11-14T11:50:27Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: ntsekouras <[email protected]>
Co-authored-by: mcsf <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

mcsf

Looks good overall, and I'd be up for merging this, but I still raised a question about hooks vs. any alternatives.

That said, hooking by post type seems totally reasonable.