The Case of the Broken Magento 2 Breadcrumbs

Published by John on December 15, 2020 Under Magento

Recently, I ran into an odd issue, where in some cases, breadcrumbs were not working on product pages for a Magento 2.4 Ecommerce store.

There didn’t seem to be much rhyme or reason to it, as some products would work, but others would not, so after playing with settings and disabling/enabling plugins, I dug into the code a bit to see how the breadcrumbs are generated.

How Breadcrumbs are generated

When attempting to generate breadcrumbs for a product, Magento 2 starts with a URL and uses it to generate breadcrumbs. For the purpose of this example, we will assume it is using the product URL in the visitors browser to generate breadcrumbs and ‘.html’ for your product and category suffix. However, there is a setting(see below) to use the referrer instead of the browser URL.

Lets say this is the product URL: mystore.com/category1/category2/product.html

The breadcrumb script will parse the first category as: mystore.com/category1/category2.html

Next, it will search your top nav for this URL with a parent element of class=category-item. If it finds this element, the navigation element’s text is used for the text of the breadcrumb.

If your top navigation does not have a link to ‘category2.html’ with a parent element of class=category-item, then breadcrumbs will not work for that category.

Referrer vs URL Based Breadcrumbs

Magento has a setting that controls whether to use the category in the URL or not: Stores -> Configuration -> Catalog -> Catalog -> Search Engine Optimization -> Use Categories Path for Product URLs

When that is set to Yes, by default, Magento will use the browser URL to attempt to generate breadcrumbs.

When it is set to No, the referrer is used, so if you visit the product directly, breadcrumbs will not work, even if the URL has the category in it(like if a different plugin is overriding the URLs). However, breadcrumbs will work when you visit from a category page.

Conclusion

When you think about it, this behavior sort of makes sense, as if you were to ONLY use the URL of a product, you wouldn’t know what to use for the text of the link and would have to make guesses on capitalization. However, on the other hand, on any large store, you probably don’t want to have ALL categories in your top navigation, so relying on this to generate breadcrumbs is obviously going to be problematic.

The easy solution is to make sure you have link elements like this for all your categories, even if you were to hide them with css:

<li class='category-item'><a ref='{CATEGORY_URL}'>Category Name</a></li>

And, it doesn’t have to be an <li> element either, it could be a <p>, <span>, etc.

I’m currently looking into a better/different solution and will try to update this post if/when I determine a better way of doing it.

No Comments |