Customizing Breadcrumbs in Rank Math SEO Plugin

Rank Math offers built-in breadcrumb settings via the WordPress dashboard under Rank Math SEO → General Settings → Breadcrumbs. These settings allow you to enable, style, and position breadcrumbs across your site.

However, if you need to go beyond the UI options and customize breadcrumbs programmatically, you can use a variety of code snippets. Below are examples to help you extend and control breadcrumb behavior in Rank Math.

All the images in the post are taken from Rank Math website.

Where to Place Your Breadcrumb Filters

Before diving into the code snippets, it is important to know where to add them. Rank Math recommends creating a dedicated rank-math.php file in your theme folder (/wp-content/themes/your-theme/rank-math.php).

This approach has three advantages over adding code to functions.php:

1. The code only runs when Rank Math is active, avoiding errors if the plugin is deactivated.
2. You can easily transfer your customizations to a new theme by copying the file.
3. It keeps your WordPress hooks organized and separate from other theme logic.

If your theme does not load rank-math.php automatically, you can include it from functions.php with a simple check:

/**
 * Load Rank Math customizations if the plugin is active.
 */
if ( class_exists( 'RankMath' ) ) {
    require_once get_stylesheet_directory() . '/rank-math.php';
}

1. Remove Breadcrumbs from the Homepage

The following code displays breadcrumbs on all pages except the homepage. Add it to your theme’s template file where breadcrumbs should appear.

/**
 * Display breadcrumbs on all pages except homepage
 */
if ( function_exists('rank_math_the_breadcrumbs') && !is_home() ) {
    rank_math_the_breadcrumbs();
}

2. Add a Blog Page to Your Breadcrumbs

If you’ve assigned a static page as your blog, enable the “Show Blog Page” option under Rank Math SEO → General Settings → Breadcrumbs.

If the option is not available (for example, if no static blog page is set), use the following filter to insert a custom “Blog” link into your breadcrumbs. Replace https://yourdomain.com/blog with the correct URL.

/**
 * Filter to add a 'Blog' page to Rank Math Breadcrumbs.
 */
add_filter( 'rank_math/frontend/breadcrumb/items', function( $crumbs, $class ) {

    if ( is_home() || is_front_page() ) {
        return $crumbs;
    }

    $blog = ['Blog', 'https://yourdomain.com/blog'];

    if (count($crumbs) < 3) {
        array_splice( $crumbs, 0, 0, array($blog) );
    } else {
        array_splice( $crumbs, 1, 0, array($blog) );
    }

    return $crumbs;
}, 10, 2);

3. Shorten the Post Title in Breadcrumbs

This filter limits the number of characters displayed for the post title in breadcrumbs. You can change the $max_char_limit to suit your design.

/**
 * Filter to shorten the post title of Rank Math Breadcrumbs.
 */
add_filter( 'rank_math/frontend/breadcrumb/items', function( $crumbs, $class ) {
    $title = get_the_title();
    $max_char_limit = 19;

    if ( strlen($title) > $max_char_limit ) {
        $short_title = substr($title, 0, $max_char_limit) . '...';
        array_splice($crumbs, count($crumbs) - 1, 1);
        $crumbs[][0] = $short_title;
    }

    return $crumbs;
}, 10, 2);

4. Display Tags in Breadcrumbs

To show tags in your breadcrumbs, go to Rank Math SEO → Titles & Meta → Posts and set the Primary Taxonomy to “Categories”. Then add the following filter to insert tags before the post title:

/**
 * Filter to display tags in Rank Math Breadcrumbs.
 */
add_filter( 'rank_math/frontend/breadcrumb/items', function( $crumbs, $class ) {
    $tags = get_the_tags();

    if ( $tags ) {
        foreach ( $tags as $tag ) {
            $crumb = [ $tag->name, get_tag_link( $tag->term_id ) ];
            array_splice( $crumbs, 2, 0, array($crumb) );
        }
    }

    return $crumbs;
}, 10, 2);

5. Remove Categories from Breadcrumbs on Posts

To remove category links from breadcrumbs on single posts, use the snippet below. This does not affect archive or taxonomy pages.

/** 
 * Filter to remove categories from Rank Math Breadcrumbs on single posts.
 */ 
add_filter( 'rank_math/frontend/breadcrumb/items', function( $crumbs, $class ) { 
    if ( is_singular('post') ) {
        unset( $crumbs[1] );
        $crumbs = array_values($crumbs);
    }

    return $crumbs; 
}, 10, 2);

This filter will not remove the breadcrumbs on your archive pages. You can refer to this guide to remove categories from breadcrumb trails on archive pages.

Other Useful Breadcrumb Filters

The examples above all use the rank_math/frontend/breadcrumb/items filter. Rank Math provides several additional filters for different types of customization:

• rank_math/frontend/breadcrumb/settings – Override breadcrumb settings like the home link display, separator character, and ancestor visibility.
• rank_math/frontend/breadcrumb/strings – Change text strings such as the breadcrumb prefix, home label, 404 text, and search/archive formats.
• rank_math/frontend/breadcrumb/args – Modify the HTML wrapper, delimiter, and before/after elements.
• rank_math/frontend/breadcrumb/html – Filter the final rendered HTML output of the entire breadcrumb trail.
• rank_math/snippet/breadcrumb – Modify the BreadcrumbList schema output only, without changing the visible breadcrumbs.

The rank_math/frontend/breadcrumb/items filter affects both the visible trail and the schema. If you only need to change the structured data, use rank_math/snippet/breadcrumb instead.

You can find the full list of available filters in the Rank Math developer documentation.

FAQs

Common questions about customizing breadcrumbs in Rank Math:

Summary

With just a few filters, you can take full control over how breadcrumbs appear on your site. Whether you are simplifying titles, customizing structure, or injecting content dynamically, these code snippets give you complete flexibility.

Rank Math provides the rank_math/frontend/breadcrumb/items filter for modifying individual breadcrumb items, along with additional hooks for changing settings, strings, HTML output, and schema data. Place your filters in a dedicated rank-math.php file for clean, maintainable code.

If you run into any issues or need help adapting these to your specific theme, feel free to reach out or check the Rank Math knowledge base for more examples.