Skip to main content
Development

Introducing Breadcrumb for Craft CMS

Posted: 04 May 2020. Updated: 08 Jun 2020

This free plugin generates a simple breadcrumb trail.

Image for Breadcrumb

Introduction

Breadcrumb was first released in March 2019, so I’m a little late with this introduction.

The first release of Breadcrumb displayed a breadcrumb trail that was based on the current URL segments.

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 segment.

Requirements

  • Craft 3.1 or above

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
  • Full control over the output using Twig

If you're looking for a Twig only solution (no plugin required), 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 %}
TWIG

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 %}
TWIG

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>
TWIG

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) %}
TWIG

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) %}
TWIG

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) %}
TWIG

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) %}
TWIG

Installation

To install the plugin, search for "Breadcrumb" in the Craft Plugin Store, or install manually using composer:

composer require youandmedigital/breadcrumb
COMMAND LINE

Feedback

If you have any issues, feedback or ideas, please feel free to submit an issue on Github.

Read this next

Weeknote #2

Weeknote #2 for the week ending 3rd May 2020.

  1. Home
  2. Notes
  3. Introducing Breadcrumb for Craft CMS
Illustration of Jon Leverrier

Ready to discuss your next project?