Breadcrumb block filters – Make WordPress Core
Skip to content
Make WordPress Core
Welcome!
The WordPress
core
Core
Core is the set of software required to run WordPress. The Core Development Team builds WordPress.
development team builds WordPress! Follow this site for general updates, status reports, and the occasional code debate. There’s lots of ways to contribute:
Found a
bug
bug
A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority.
Create a ticket
in the bug tracker.
Want to contribute?
Get started quickly with tickets marked as
good first bugs
for new contributors or join a
bug scrub
. There’s more on the
reports page
, like
patches needing testing
, and on
feature projects page
Other questions?
Here is a detailed
handbook for contributors
, complete with tutorials.
Communication
Core uses
Slack
for real-time communication. Contributors live all over the world, so there are discussions happening at all hours of the day.
Core development meetings are every Wednesday at
15:00 UTC
in the
#core
channel on
Slack
. Anyone can join and participate or listen in!
WordPress 7.0 introduces a new
Breadcrumbs
block
Block
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
header
Header
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.
Breadcrumbs block in a header template part using Twenty Twenty-Five theme, here showing the trail for a child page
Two filters provide developers with control over the breadcrumb trail output.
block_core_breadcrumbs_items
This
filter
Filter
Filters are one of the two types of 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:
label
(string) — the breadcrumb text.
an optional
url
(string) — the breadcrumb link
URL
URL
A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org
an optional
allow_html
(bool) — whether to allow
HTML
HTML
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
taxonomy
Taxonomy
A taxonomy is a way to group things together. In WordPress, some common taxonomies are category, link, tag, or post format.
, 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
tag
tag
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.)
categories
tags
specific tag
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
Gutenberg
Gutenberg
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.
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
Share this:
Share on Threads (Opens in new window)
Threads
Share on Mastodon (Opens in new window)
Mastodon
Share on Bluesky (Opens in new window)
Bluesky
Share on X (Opens in new window)
Share on Facebook (Opens in new window)
Share on LinkedIn (Opens in new window)
👏 nice, ty.
Leave a Reply
Cancel reply
You must be
logged in
to post a comment.
This site uses Akismet to reduce spam.
Learn how your comment data is processed.
Site resources
Email Updates
Enter your email address to subscribe to this blog and receive notifications of new posts by email.
Join 6,694 other subscribers
Recent Updates
Recent Comments
No Replies
Current Release
The current release in progress is
WordPress 7.0
. Planned future releases are listed on
the Project Roadmap
. Feature projects not tied to specific releases can be found on
the Features page.
Regular Chats
Note:
All chats happen on
Slack
Weekly Developer Meetings
: [time relative]Wednesday 15:00 UTC[/time] in
#core
About the Dev Chat
Agendas
Summaries
Performance Weekly Chat
[time relative]Tuesday 15:00 UTC[/time] in
#core-performance
New Contributors Chat
The 2nd and 4th Wednesday of every month at 17:00 UTC in
#core
See all meetings →
Recent Posts and Comments
Team Pledges
2664 people
have pledged time to contribute to Core Team efforts! When looking for help on a project or program, try starting by reaching out to them!
compose new post
reply
edit
go to top
go to the next post or comment
go to the previous post or comment
toggle comment visibility
esc
cancel edit post or comment
Loading Comments...
You must be
logged in
to post a comment.