| Decide: core vs Easy Breadcrumb vs custom builder |
Overview & Decision |
Use core PathBasedBreadcrumbBuilder when basic path-hierarchy breadcrumbs are sufficient. Use Easy Breadcrumb when you need real page titles, current page as final segment, or JSON-LD SEO output. |
| Understand the breadcrumb system architecture |
Core Breadcrumb Architecture |
Read this before writing any custom builder or alter hook. The BreadcrumbManager is the chain dispatcher; every breadcrumb request routes through it. |
| Know which core builders handle what |
Core Breadcrumb Builders |
Know which builder handles which route so you can decide where to inject custom logic. All core builders register at priority 0 except where noted. |
| Install and configure Easy Breadcrumb |
Easy Breadcrumb Module |
Use Easy Breadcrumb when core produces ugly URL-slug titles (e.g., "my-blog-post" instead of "My Blog Post"), when you need the current page title as the last crumb, or when you need built-in JSON-LD SEO output. It is the de facto standard… |
| Tune Easy Breadcrumb settings |
Easy Breadcrumb Configuration |
After installing Easy Breadcrumb, configure at admin/config/user-interface/easy-breadcrumb. All settings map to easy_breadcrumb.settings.yml which can be exported and version-controlled. |
| Write a custom breadcrumb builder |
Custom Breadcrumb Builder |
Use a custom builder when breadcrumbs must be driven by entity relationships (not URL structure), or when you need different logic for specific routes. Use hook_system_breadcrumb_alter() instead for minor adjustments. |
| Alter breadcrumbs with a hook |
Altering Breadcrumbs |
Use hook_system_breadcrumb_alter() for low-overhead adjustments after a builder runs: inserting a segment, removing a specific link, adding cache tags/contexts. For complex logic involving entity loading or routing, write a custom… |
| Add JSON-LD structured data for SEO |
Structured Data (SEO) |
Add JSON-LD breadcrumb structured data to help Google display breadcrumbs in search results instead of the raw URL. This is a meaningful SEO win for content-heavy sites. |
| Theme the breadcrumb output |
Twig Theming |
Override the default breadcrumb template when you need custom markup: different HTML structure, additional CSS classes, aria attributes, or schema microdata. The template override requires no PHP — just create the file in the right place. |
| Use breadcrumbs with UI Suite DaisyUI |
UI Suite DaisyUI Integration |
When your theme extends ui_suite_daisyui, the theme's breadcrumb.html.twig delegates to the ui_suite_daisyui:breadcrumbs SDC automatically. You get DaisyUI breadcrumb styling with no extra code. |
| Understand breadcrumb caching |
Caching |
Breadcrumbs render via BigPipe (the SystemBreadcrumbBlock uses createPlaceholder(): true). Cache metadata on the Breadcrumb object directly controls invalidation. |
| Place the breadcrumb block |
Block Placement |
The SystemBreadcrumbBlock (plugin ID system_breadcrumb_block) is the only standard way to render breadcrumbs in a region. Place via the Block UI or via config YAML for themes, recipes, or installation profiles. |
| Avoid common pitfalls |
Best Practices & Anti-Patterns |
Read this before writing any breadcrumb-related code. These are the patterns that cause production issues and the ones that solve them. |
| Handle special breadcrumb scenarios |
Common Recipes |
Ready-to-apply patterns for the most frequent breadcrumb requirements. Each recipe is self-contained. |