TSF v5.0 added breadcrumbs to every post, page, term, and archive. These are outputted for search engines via structured data, but you can also output them directly on your site via a shortcode.

Basic syntax

The most basic form of the shortcode:

Separator attribute

You can add a custom separator to the breadcrumb:

Please note that the separator is added via the CSS content property. HTML-encoded entities, like •, won’t work. And, because WordPress sometimes outputs backward solidi (\) incorrectly, you may need to add two backslashes to use CSS-encoded Unicode. So, for a bullet (•), you’d have to use [tsf_breadcrumb sep="\\2022"].

WordPress is perfectly capable of storing Unicode since version 4.2. So, to work around all these issues, we recommend inserting special entities directly:

Home attribute

To rename the Home crumb, use the “home” attribute:

Any attributes can be combined in a single shortcode, here, we change the home label and the separator:

An empty home value removes the Home crumb. On your homepage, the only crumb is the page you’re on, so it stays with that page’s title.

home="0" is the label 0, so that crumb stays. [tsf_breadcrumb home] without a value does not remove it: WordPress does not pass that attribute, and the label stays Home.

Maximum crumbs

max limits how many crumbs the shortcode shows. Leave it out to show the whole shortcode trail. A value below 3 is treated as 3. When the trail is longer than max, the first crumb stays, an ellipsis replaces the middle, and the last crumbs fill the rest. The ellipsis doesn’t count toward max.

This page’s trail is too short to collapse, so the demos below use a deeper one. Its crumbs are Home, Category, Subcategory, Parent page, Subpage, and Deep page. Deep page stands in for the page you’re on:

With max="4", the shortcode keeps Home and the last three crumbs:

When you combine max with an empty home, the shortcode removes the Home crumb first. The ellipsis then follows the first crumb that remains:

Title attribute

You can choose which title type to use for breadcrumb items. By default, the shortcode uses the setting configured under SEO Settings → Schema.org → Breadcrumbs.

To override the setting, use [tsf_breadcrumb title="meta"] to consider meta titles which may include custom overrides, or [tsf_breadcrumb title="page"] to use plain page titles.

Class attribute

Finally, you can change the class. You’ll need this if you want to output a different type of separator (we did that without telling you for the examples above). The syntax is as follows, and is meant for developers that implement custom CSS: [tsf_breadcrumb class="my-example-class"]

Which crumbs does the breadcrumb trail include?

The shortcode and structured data share one trail. The shortcode only trims it with the rules above.

On a post, page, or product, the trail lists these crumbs in order:

• Your homepage.
• The post type archive, when the post type has one. For WooCommerce products, that’s the shop page.
• The primary term and its parent terms, from one taxonomy.
• The parent pages, when the post type has them. Parent pages that visitors can’t view, such as drafts, are left out.
• The page you’re on.

On a term archive, the trail lists your homepage, the parent terms, and the term. On author, date, post type archive, search, and 404 pages, the trail lists your homepage and that page. Archive crumbs show the archive’s name without a prefix like “Category:”, “Archives:”, or “Author:”. Meta titles you wrote appear as written when you use meta titles for breadcrumbs.

Breadcrumb trail settings

You can change two parts of the trail under SEO Settings → Schema.org → Breadcrumbs. Both settings apply per post type, and both change the shortcode and structured data.

Taxonomy Crumb: This setting picks which taxonomy supplies the terms. Default uses the first taxonomy with parent and child terms that WordPress registered for that post type. The option shows that taxonomy’s name. On WooCommerce 9.6 and later, Default is Brands for products. Select Product categories to use categories instead. Exclude taxonomy crumb leaves the terms out. When a post has several terms in that taxonomy, the trail follows the primary term you selected in the post editor.

Post Type Archive Crumb: Clear a post type’s checkbox to leave its archive out of the trail. For WooCommerce products, this removes the shop page.

How do breadcrumbs wrap on narrow screens?

The shortcode wraps its crumbs onto the next line as whole crumbs, so a long crumb name no longer breaks mid-word. The shortcode’s list also drops the inline-start padding that some WordPress themes add to lists.

Filters for developers

Three WordPress filters change the shortcode and its trail:

• the_seo_framework_breadcrumb_list filters the generated trail that the shortcode and structured data share. Every crumb needs a role next to its url and name. Without a role, the shortcode causes a PHP warning.
• the_seo_framework_breadcrumb_shortcode_css filters the CSS rules of the shortcode. Returning no rules also removes the <style> element.
• the_seo_framework_breadcrumb_shortcode_output filters the final output. It also passes the crumbs the shortcode rendered, and the trail before the home and max attributes changed it.

Crumb roles are home, pta (post type archive), archive-N (terms, outermost first), page-N (parent pages), current, and current-home (the only crumb on your homepage).