Custom Breadcrumbs
Provides a configuration entity system for creating and managing custom breadcrumbs on content entity pages, views, page manager, and other controller pages.
custom_breadcrumbs
Install
composer require 'drupal/custom_breadcrumbs:^1.1'
Overview
Custom Breadcrumbs is a powerful module that allows site administrators to define and manage custom breadcrumb trails for any content entity type in Drupal. Unlike default breadcrumb systems that rely on URL structure, this module provides complete control over breadcrumb paths and titles through a user-friendly admin interface.
The module supports two types of breadcrumb definitions: content entity-based breadcrumbs that apply to specific entity types and bundles, and path-based breadcrumbs that match URL patterns with wildcards. Both types support full Token integration for dynamic breadcrumb generation.
Key capabilities include taxonomy term hierarchy integration for automatic breadcrumb trees, language-specific breadcrumb configurations for multilingual sites, customizable home link settings, current page title display options, and cache context management for query parameter-based breadcrumbs. The module also provides a pseudo-field that can display breadcrumbs within entity view modes, useful for displaying breadcrumbs on node teasers in search results.
Features
- Create custom breadcrumb configurations as config entities with enable/disable status
- Define breadcrumbs for any content entity type (nodes, taxonomy terms, users, etc.) with bundle-level specificity
- Create path-based breadcrumbs using URL patterns with wildcard (*) support
- Full Token module integration for dynamic breadcrumb paths and titles
- Taxonomy term hierarchy integration using <term_hierarchy:field_name> syntax for automatic breadcrumb trees
- Language-specific breadcrumb configurations for multilingual sites
- Configurable home link with customizable text
- Option to append current page title as the last breadcrumb item with optional linking
- Title length trimming with configurable character limit
- Ability to disable custom breadcrumbs on admin pages
- Site-wide breadcrumb mode for applying basic breadcrumbs to all pages
- <nolink> syntax for creating breadcrumb items without links
- Extra cache contexts configuration for proper caching with query parameters
- Pseudo-field for displaying breadcrumbs within entity view modes
- Config translation support for translating breadcrumb settings
Use Cases
Custom breadcrumbs for article content type
Create a breadcrumb trail for all article nodes that shows Home > News > [Article Title]. Go to Structure > Custom breadcrumbs, add a new breadcrumb with Type = Content entity, Entity type = node, Entity bundle = article. Set Breadcrumb paths to '/news' and Breadcrumb titles to 'News'. Enable 'Append current page title' in global settings to include the article title.
Taxonomy term hierarchy breadcrumbs
Display the full taxonomy hierarchy as breadcrumbs for nodes tagged with a category term. Create a breadcrumb configuration for your content type and use '<term_hierarchy:field_categories>' in the Breadcrumb paths field (where field_categories is your taxonomy reference field). This automatically creates breadcrumb links for each parent term.
Search results with query-based breadcrumbs
Create breadcrumbs for a search results page that includes the search query. Create a path-based breadcrumb matching '/search/*'. Use the Token module to include query values. Add 'url.query_args:search' to Extra cache contexts to ensure proper caching per search query.
Multilingual breadcrumbs
Configure different breadcrumb trails for each language. Create multiple breadcrumb configurations for the same entity type/bundle, each with a different language selected. The module will automatically display the appropriate breadcrumb based on the current interface language.
Breadcrumbs on node teasers
Display breadcrumbs within node teasers (useful for search results). Go to the content type's Manage display settings, switch to the Teaser view mode, and enable the 'Breadcrumbs' field. Position it where you want breadcrumbs to appear within the teaser.
Non-linked breadcrumb items
Create a breadcrumb trail where some items are not clickable links. Use '<nolink>' as the path for items that should display as text only. For example: Breadcrumb paths = '/products' and '<nolink>', Breadcrumb titles = 'Products' and 'Current Category'.
Views page breadcrumbs
Add custom breadcrumbs to Views pages. Create a path-based breadcrumb with the Path pattern matching your Views page URL (e.g., '/blog' or '/products/*'). Define the desired breadcrumb paths and titles for these pages.
Tips
- Use path-based breadcrumbs for Views pages, custom controllers, and any pages that don't have content entities
- The breadcrumb service has priority 1003, which is higher than most other breadcrumb builders, ensuring your custom breadcrumbs take precedence
- Combine Token integration with taxonomy hierarchy for complex nested category breadcrumbs
- Enable 'Site wide breadcrumbs' to ensure all pages get at least basic breadcrumb functionality with home link and current page title
- Use the Manage display pseudo-field feature to include breadcrumbs in node teasers for improved search result navigation
- Remember that breadcrumb configurations can be exported and imported with Drupal's configuration management system
Technical Details
Admin Pages 4
/admin/structure/custom-breadcrumbs
Main listing page displaying all configured custom breadcrumb entities. Shows breadcrumb label, entity type, entity bundle, language, and enabled/disabled status. Provides operations to edit, delete, or enable/disable each breadcrumb configuration.
/admin/structure/custom-breadcrumbs/add
Form for creating a new custom breadcrumb configuration. Allows specifying the breadcrumb type (content entity or path-based), target entity type and bundle, language, breadcrumb paths and titles with Token support.
/admin/structure/custom-breadcrumbs/{custom_breadcrumbs}
Form for editing an existing custom breadcrumb configuration. Same fields as the add form with current values populated.
/admin/config/user-interface/custom-breadcrumbs
Global settings for the Custom Breadcrumbs module. Configure default behaviors for home link, current page display, and other site-wide options.
Permissions 1
Hooks 3
hook_entity_extra_field_info
Implements hook_entity_extra_field_info() to provide a 'Breadcrumbs' pseudo-field for all content entity bundles. This allows breadcrumbs to be displayed within entity view modes through the Manage display interface.
hook_entity_view
Implements hook_entity_view() to render breadcrumbs when the 'breadcrumbs' component is enabled in the entity display. Useful for showing breadcrumbs on node teasers in search results.
hook_help
Implements hook_help() to provide help text from README.md on the module help page. Supports Markdown rendering if the Markdown module is available.
Troubleshooting 5
Verify the breadcrumb configuration is enabled (status = checked). Ensure the entity type and bundle match exactly. Check if 'Disable on admin pages' is enabled for admin pages. Clear caches after making changes.
Add the appropriate cache context to the 'Extra cache contexts' field. For example, use 'url.query_args:search' for search query parameters. This ensures breadcrumbs are cached separately for different query values.
Ensure the Token module is properly installed. Verify you're using the correct token syntax (e.g., [node:title] for nodes). Use the Token browser in the breadcrumb form to find valid tokens for your entity type.
Use the syntax '<term_hierarchy:field_name>' where field_name is the machine name of your taxonomy term reference field. Ensure the field exists on the content type and contains term references.
Create separate breadcrumb configurations for each language. Set the 'Language' field to the specific language code. For fallback breadcrumbs, create one with 'Language not specified' which will be used when no language-specific configuration exists.
Security Notes 3
- The module uses XSS filtering for home link text to prevent script injection
- All breadcrumb URLs are validated to require leading slashes or valid Token syntax
- Admin permission 'administer custom_breadcrumbs' is required for all configuration changes