Breadcrumb block filters

WordPress 7.0 introduces a new Breadcrumbs blockBlock 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. that can be placed once — such as in a theme’s headerHeader 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’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. — and automatically reflects the site’s navigation hierarchy.

Two filters provide developers with control over the breadcrumb trail output.

block_core_breadcrumbs_items

This filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. 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. allows developers to modify, add, or remove items from the final breadcrumb trail just before rendering. Each item is an array with three properties:

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

Example: Prepend a custom breadcrumb item

  add_filter( 'block_core_breadcrumbs_items', function ( $breadcrumb_items ) {
        array_unshift( $breadcrumb_items, array(
                'label' => __( 'Shop', 'myplugin' ),
                'url'   => home_url( '/shop/' ),
        ) );

        return $breadcrumb_items;
  } );

block_core_breadcrumbs_post_type_settings

When a post type has multiple taxonomies or when a post is assigned to multiple terms within a taxonomyTaxonomy 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., 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 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.).

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’s “Prefer taxonomy terms” setting is enabled (under advanced settings). It does not affect hierarchical ancestor-based trails (e.g., parent/child pages).

The filter receives three parameters:

• $settings (array) — an empty array by default. Callbacks should populate the array and return it with the following optional keys:
  • taxonomy (string) — taxonomy slug to use for breadcrumbs.
  • term (string) — term slug to prefer when the post has multiple terms in the selected taxonomy.
• $post_type (string) — the post type slug.
• $post_id (int) — the post ID, enabling per-post customization.

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 1: Set a preferred taxonomy and term per post type

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

Example 2: Choose a specific term per post

add_filter( 'block_core_breadcrumbs_post_type_settings', function ( $settings, $post_type, $post_id ) {
	if ( $post_type !== 'post' ) {
		return $settings;
	}
	
	$terms = get_the_terms( $post_id, 'category' );

	if ( $terms ) {
		$settings['taxonomy'] = 'category';
		$settings['term']     = end( $terms )->slug;
	}

	return $settings;
}, 10, 3 );

See GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ pull requests: 74169, 73283, 74170.

Props to @karolmanijak, @ntsekouras for the implementation.

Props to @karolmanijak for technical review.

Props to @mcsf for copy review.

#dev-notes, #7-0

#dev-notes-7-0