Customizing Breadcrumb Trails with Hooks

BreadcrumbsPress provides filters at different stages of building a trail for the current request. Choose the narrowest hook that matches your task, and first check whether Settings already provides the path or title you need.

Add the examples to a site-specific plugin or a child theme’s functions.php. Register callbacks before a trail is built. Filters receive a value and must return it, including when the callback makes no change. Test the front end and clear any page cache after changes.

Choose a stage

• Generator build accepts a proposed trail before the normal page-type builders. Returning a nonempty array skips those fallback builders. It is skipped on home and posts pages.
• Builder filters modify the trail for a particular kind of page. For example, single post type, post type archive, taxonomy term archive, and search results each have their own filter and arguments.
• Generator complete runs after the current trail has been built, including for home and posts pages.

These generator hooks are for the current-request trail; they are not universal hooks for trails built directly for a specific post or term. A nonempty current trail is cached for the request, so register callbacks before the first build. The array contains Crumb objects in display order. Preserve the array and its objects when making a targeted change.

Change a trail for one post type

The generic single-post-type filter receives the post ID and type. The type-specific filter runs afterward and uses the actual post type name in its hook name. For example, replace book with your registered post type:

add_filter( 'breadcrumbspress_builder_for_post_type_single_book', function( $breadcrumbs, $post_id ) {
    if ( isset( $breadcrumbs['home'] ) ) {
        $breadcrumbs['home']->title = 'Library home';
    }

    return $breadcrumbs;
}, 10, 2 );

This changes the home crumb title only if that key exists. The final 2 lets the callback receive both arguments. Other filters may still change the result later. Taxonomy archives follow the same pattern: the generic term filter runs before the taxonomy-specific filter. Use the real taxonomy slug as its suffix.

Change the completed current trail

For a change across current-request page types, use the complete filter. This example changes the home title when the trail contains a home crumb:

add_filter( 'breadcrumbspress_generator_complete', function( $breadcrumbs ) {
    if ( isset( $breadcrumbs['home'] ) ) {
        $breadcrumbs['home']->title = 'Start';
    }

    return $breadcrumbs;
} );

For integration setup that must run once the plugin has registered its shortcodes, see the plugin core ready action. Register that action callback before it fires at init priority 20; register trail filters before the relevant trail is built.

To control whether a current trail is shown or how its request is classified, see Control Visibility and Request Detection.