[{"id":121761,"date":"2026-03-04T16:35:33","date_gmt":"2026-03-04T16:35:33","guid":{"rendered":"https:\/\/make.wordpress.org\/core\/?p=121761"},"modified":"2026-03-05T22:37:16","modified_gmt":"2026-03-05T22:37:16","slug":"breadcrumb-block-filters","status":"publish","type":"post","link":"https:\/\/make.wordpress.org\/core\/2026\/03\/04\/breadcrumb-block-filters\/","title":{"rendered":"Breadcrumb block filters"},"content":{"rendered":"

WordPress 7.0 introduces a new Breadcrumbs<\/code> blockBlock<\/span> Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.<\/span><\/span><\/span> that can be placed once \u2014 such as in a theme\u2019s headerHeader<\/span> The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor\u2019s opinion about your content and you\/ your organization\u2019s brand. It may also look different on different screen sizes.<\/span><\/span><\/span> \u2014 and automatically reflects the site\u2019s navigation hierarchy.<\/p>\n\n\n\n

\"\"
Breadcrumbs block in a\u00a0header template part\u00a0using Twenty Twenty-Five theme, here showing the trail for a child page<\/figcaption><\/figure>\n\n\n\n

Two filters provide developers with control over the breadcrumb trail output.<\/p>\n\n\n\n

block_core_breadcrumbs_items<\/h3>\n\n\n\n

This filterFilter<\/span> Filters are one of the two types of Hooks https:\/\/codex.wordpress.org\/Plugin_API\/Hooks<\/a>. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output.<\/span><\/span><\/span> allows developers to modify, add, or remove items from the final breadcrumb trail just before rendering. Each item is an array with three properties:<\/p>\n\n\n\n

    \n
  1. label<\/code> (string) \u2014 the breadcrumb text.<\/li>\n\n\n\n
  2. an optional url<\/code> (string) \u2014 the breadcrumb link URLURL<\/span> A specific web address of a website or web page on the Internet, such as a website\u2019s URL www.wordpress.org<\/span><\/span><\/span>.<\/li>\n\n\n\n
  3. an optional allow_html<\/code> (bool) \u2014 whether to allow HTMLHTML<\/span> HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers.<\/span><\/span><\/span> in the label. When true<\/code>, the label will be sanitized with wp_kses_post()<\/code>, allowing only safe HTML tags. When false<\/code> or omitted, all HTML will be escaped with esc_html()<\/code>.<\/li>\n<\/ol>\n\n\n\n

    Example: Prepend a custom breadcrumb item<\/p>\n\n\n\n

      add_filter( 'block_core_breadcrumbs_items', function ( $breadcrumb_items ) {\n        array_unshift( $breadcrumb_items, array(\n                'label' => __( 'Shop', 'myplugin' ),\n                'url'   => home_url( '\/shop\/' ),\n        ) );\n\n        return $breadcrumb_items;\n  } );<\/code><\/pre>\n\n\n\n
    block_core_breadcrumbs_post_type_settings<\/h3>\n\n\n\n
    When a post type has multiple taxonomies or when a post is assigned to multiple terms within a taxonomyTaxonomy<\/span> A taxonomy is a way to group things together. In WordPress, some common taxonomies are category, link, tag, or post format. https:\/\/codex.wordpress.org\/Taxonomies#Default_Taxonomies<\/a>.<\/span><\/span><\/span>, there could be numerous ways to construct the breadcrumbs trail. For example in a post that has both categories and tags a user might want to show in the breadcrumbs trail the categories (default), the tags and\/or select a specific tagtag<\/span> A directory in Subversion. WordPress uses tags to store a single snapshot of a version (3.6, 3.6.1, etc.), the common convention of tags in version control systems. (Not to be confused with post tags.)<\/span><\/span><\/span>.<\/p>\n\n\n\n
    \n
    \"\"<\/a>
    categories<\/figcaption><\/figure>\n\n\n\n
    \"\"<\/a>
    tags<\/figcaption><\/figure>\n\n\n\n
    \"\"<\/a>
    specific tag<\/figcaption><\/figure>\n<\/figure>\n\n\n\n
    This filter controls which taxonomy and terms appear in the Breadcrumbs block trail for posts that use taxonomy-based breadcrumbs. It applies to non-hierarchical post types (e.g., posts, products) or hierarchical post types when the block\u2019s \u201cPrefer taxonomy terms\u201d setting is enabled (under advanced settings). It does not affect hierarchical ancestor-based trails (e.g., parent\/child pages).<\/p>\n\n\n\n
    The filter receives three parameters:<\/p>\n\n\n\n