Customizing your Breadcrumbs

  • Noah Siegrist

The breadcrumb is a navigation feature, where the user gets presented step by step the way back to the home page. All they have to do is picking the breadcrumbs up, just like in Hansel and Gretel. Although, this may seem rather simple, most sites actually use fairly complex patterns.

Drupal core provides us with builder services ordered by a priority. More builders can be found in contrib modules and you always can create custom builders yourself. Builder are services - if you aren’t familiar with them - this might be helpful.

The core path based builder

In case your URL patterns exactly represent your breadcrumb, you struck gold. Drupal core provides us with a PathBasedBreadcrumbBuilder which is enabled by default and therefore doesn’t need a set up.
However, in case you want some configurable options - such as editing or hiding the home link and excluding pages - the “Easy Breadcrumb” (easy_breadcrumb) module could come in handy. After the installation, the mentioned configuration page in the backend can be found under “”.

The contrib menu based builder

Path based breadcrumbs covers most use cases. However, sometimes the content manager needs more configuration control. In this case it could make sense to have the breadcrumb follow the exact structure of the menu defined by the core menu without regarding the URL path.
To achieve this, one can utilize the “Menu Breadcurmb” (menu_breadcrumb) module. This builder service relies on the active trail provided by the core service “@menu.active_trail”. Configuration for that module can be found under the URL “”, You can choose the menus to be represented, set whether or not the home link shall be included and the current page needs to be appended.

Manually adding each node to the menu in order to show up in the menu-based breadcrumb is not necessary. The “Menu Position” (menu_position) module allows you to dynamically add nodes to the active trail based on conditional rules, provided by the Condition plugin type.
There are several plugins out of the box by Drupal core. The UserRole plugin, the Language plugin, the CurrentTheme plugin and most notably the NodeType plugin, which allows you to set rules based on the node bundle.
There are many more plugins to be found in core and in contrib modules. One module to be highlighted would be the “Term Condition” (term_condition) contrib module, thanks to whom you are able to evaluate whether a taxonomy terms is referenced on one of the nodes fields now. Last but not least, in case the requirements are outstandingly peculiar you always have the option to create plugins yourself.

Disable an unwanted builder

Having created an awesome breadcrumb mechanic that covers every necessary use case, the low priority builders may be redundant. The PathBasedBreadcrumbBuilder is always able to create a breadcrumb and the only way of getting rid of it is to replace it with a non applying builder.

        class: Drupal\zoo_customizations\Builder\NoBreadcrumbBuilder
            - { name: breadcrumb_builder, priority: 0 }

In the services.yml one can override any service including the PathBasedBreadcrumbBuilder. The replacement breadcrumb builder must implement the BreadcrumbBuilderInterface and therefore the two functions applies() and build(). Unless applies() returns true in some cases build doesn't need an implementation.

 * This service overrides the PathBasedBreadcrumbBuilder effectively disabling it.
 * Class NoBreadcrumbBuilder.
 * @package Drupal\zoo_customizations\Builder
class NoBreadcrumbBuilder implements BreadcrumbBuilderInterface {

   * @inheritdoc
  public function applies(RouteMatchInterface $route_match) {
    return FALSE;

   * @inheritdoc
  public function build(RouteMatchInterface $route_match) {
    // Wont be implemented.


Custom rendering

The frontend inclusion is done via block, in particular the “system_breadcrumb_block”, which should be included by default after installing Drupal. To get familiar with blocks, this might be helpful. The Block can also be added anywhere by using the contrib module TwigTeaks 2.x. Add the following line anywhere in your Twig templates.
{{ drupal_block('system_breadcrumb_block') }}

No matter which implementation is used, the block itself is being rendered and utilizes the breadcrumb.html.twig template.

Tell us what you think