Introduction
Breadcrumb was first released in March 2019.
The first release of Breadcrumb displayed a trail that was generated from a URL. Pretty simple.
However, since version 1.1.0, Breadcrumb generates crumb titles from a custom field if set, falling back to the title field if it's available. If those fields are missing, Breadcrumb will generate the crumb title from the URL.
Requirements
- Craft 3
- Craft 4 (support added October 2022)
- Craft 5 (support added April 2024)
Features
- Searches each page in the breadcrumb trail for a custom field or title, falling back to a title generated from the URL segment
- Can work across different Craft objects such as Entries, Categories, Tags, Users and even custom routes
- Multisite and multilingual friendly
- Can be used to generate BreadcrumbList schema
- Bring your own HTML - full control over the output using Twig
If you're looking for a Twig only solution (no plugin required), you should probably checkout the breadcrumb component by Craft Snippets.
Settings
homeTitle
string, optional, default value 'Home'
Customise the first title in the breadcrumb.
customBaseUrl
string, optional, default value '@baseUrl'
Set a custom base URL for each crumb. Use a fully qualified URL without a trailing slash.
customFieldHandleEntryId
int, optional, default value '0'
Required for customFieldHandle.
customFieldHandle
string, optional, default value 'null'
Specify a custom field to generate the crumb title from. Requires the setting customFieldHandleEntryId to work.
lastSegmentTitle
string, optional, default value 'null'
Customise the last crumb title. Can be useful when working with templates that use custom routing.
skipUrlSegment
int, optional, default value 'null'
Skip a level or segment from the breadcrumb.
limit
int, optional, default value 'null'
Limit the number of crumbs returned in the breadcrumb.
{# Element will try to be an entry, category, tag or null #}
{% set element = entry ?? category ?? tag ?? null %}
{# Breadcrumb settings #}
{% set mySettings =
{
homeTitle: '<homeTitle>',
customBaseUrl: '<customBaseUrl>',
customFieldHandleEntryId: element.id,
customFieldHandle: '<customFieldHandle>',
lastSegmentTitle: '<lastSegmentTitle>',
skipUrlSegment: <skipUrlSegment>,
limit: <limit>
}
%}
{# mySettings var is passed into the Breadcrumb config #}
{% set breadcrumb = craft.breadcrumb.config(mySettings) %}
{% if breadcrumb > 1 %}
<div class="c-breadcrumb">
<ol class="c-breadcrumb__items">
{% for crumb in breadcrumb %}
{% if loop.last %}
<li class="c-breadcrumb__item">
<span>{{ crumb.title }}</span>
</li>
{% else %}
<li class="c-breadcrumb__item">
<a class="c-breadcrumb__link" href="{{ crumb.url }}">
<span>{{ crumb.title }}</span>
</a>
</li>
{% endif %}
{% endfor %}
</ol>
</div>
{% endif %}Examples
Generate a simple breadcrumb
Use whatever markup you like.
{# set a variable called myBreadcrumb #}
{% set myBreadcrumb = craft.breadcrumb.config %}
{# If there is more than 1 item in the breadcrumb #}
{% if myBreadcrumb > 1 %}
<div class="c-breadcrumb">
<ol class="c-breadcrumb__items">
{% for crumb in myBreadcrumb %}
{# The last item in the breadcrumb #}
{% if loop.last %}
<li class="c-breadcrumb__item">
<span>{{ crumb.title }}</span>
</li>
{# A normal link in the breadcrumb #}
{% else %}
<li class="c-breadcrumb__item">
<a class="c-breadcrumb__link" href="{{ crumb.url }}">
<span>{{ crumb.title }}</span>
</a>
</li>
{% endif %}
{% endfor %}
</ol>
</div>
{% endif %}Generate BreadcrumbList schema
Using Twig, we can customise the output to generate BreadcrumbList schema.
{# set a variable called myBreadcrumbSchema #}
{% set myBreadcrumbSchema = craft.breadcrumb.config %}
<script type="application/ld+json" data-schema="BreadcrumbList">
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [
{% for crumb in myBreadcrumbSchema %}
{%- if loop.last -%}
{
"@type": "ListItem",
"position": {{ crumb.position }},
"name": "{{ crumb.title }}"
}
{%- else -%}
{
"@type": "ListItem",
"position": {{ crumb.position }},
"name": "{{ crumb.title }}",
"item": "{{ crumb.url }}"
},
{% endif -%}
{% endfor ~%}
]
}
</script>Generate a breadcrumb with a custom home title
This will set the home title to "Start" and has a Craft translation filter attached so the string can be translated.
{# Breadcrumb settings #}
{% set mySettings =
{
homeTitle: 'Start'|t
}
%}
{# mySettings var is passed into the Breadcrumb config #}
{% set breadcrumb = craft.breadcrumb.config(mySettings) %}Generate a breadcrumb with a custom base url
Breadcrumb will detect the baseUrl for the current site automatically, however if you need to set a custom baseUrl, use the customBaseUrl setting.
{#
Example 1 using a string
#}
{# Breadcrumb settings #}
{% set mySettings =
{
customBaseUrl: 'https://example.com/intro'
}
%}
{# mySettings var is passed into the Breadcrumb config #}
{% set breadcrumb = craft.breadcrumb.config(mySettings) %}
{#
Example 2 using a twig variable
#}
{# Breadcrumb settings #}
{% set mySettings =
{
customBaseUrl: myVarWithUrl
}
%}
{# mySettings var is passed into the Breadcrumb config #}
{% set breadcrumb = craft.breadcrumb.config(mySettings) %}Generate breadcrumb titles from a custom field
This setting works best when the custom field has been assigned to all Craft objects in use in your project. If the custom field is not found, Breadcrumb will next try the title field if available, falling back to the URL segment to generate the crumb title.
{# Element will try to be an entry, category, tag or null #}
{% set element = entry ?? category ?? tag ?? null %}
{# Breadcrumb settings #}
{% set mySettings =
{
customFieldHandleEntryId: element.id,
customFieldHandle: 'myCustomFieldHandle'
}
%}
{# mySettings var is passed into the Breadcrumb config #}
{% set breadcrumb = craft.breadcrumb.config(mySettings) %}Set the last crumb title on a custom routing template
Custom routes have certain tokens available that can be used as variables in your templates. If you’re familiar with Twig, you can set the value to anything you want.
{# Breadcrumb settings #}
{% set mySettings =
{
lastSegmentTitle: myVarWithCustomTitle ?? year ?? month ?? day ?? page ?? null
}
%}
{# mySettings var is passed into the Breadcrumb config #}
{% set breadcrumb = craft.breadcrumb.config(mySettings) %}Installation
To install the plugin, search for "Breadcrumb" in the Craft Plugin Store, or install manually using composer:
composer require youandmedigital/breadcrumbFeedback
If you have any issues, feedback or ideas, please feel free to submit an issue on Github.
Read this next
Weeknote #2
