Angular Breadcrumbs Component | ng-hub-ui-breadcrumbs
Angular breadcrumbs component with router integration, custom templates, RTL support and flexible styling tokens.
Last updated Sep 6, 2026
Overview
Why teams search for this library
Use these Angular breadcrumbs when route context matters and you need a navigation aid that works with the Angular Router, templates and structured navigation paths.
Install
npm install ng-hub-ui-breadcrumbsJump to
Ideal for
- documentation sites
- admin panels
- multi-level apps
- route-aware navigation
About breadcrumbs
ng-hub-ui-breadcrumbs gives Angular applications a route-aware breadcrumb component for admin panels, documentation sites and multi-level products. It is useful when navigation depth grows and users need more orientation than a back button can provide.
Feature guides
Core Features
Essential breadcrumb functionality with automatic route detection and navigation path display.
Examples:
Basic Breadcrumbs
A trail read straight from the route configuration, with nothing to wire.
Basic Breadcrumbs
A trail read straight from the route configuration, with nothing to wire.
Items are generated from the data.breadcrumb configuration of active routes.
Code
Code
Import:
Template:
Component:
Destinations Beyond the Router
Crumbs that point outside the Angular application, or at a file to download, rendered as plain anchors.
Example.com leaves the app in a new tab, Handbook downloads a file, and Docs is an ordinary in-app crumb routed through routerLink. The last crumb is never a link, whatever it declares.
Code
Import:
Template:
Component:
The Trail as a Signal
A page header that titles itself from the last crumb. `HubBreadcrumbsService.breadcrumbs` is a signal, so anything outside the component can derive from it — no subscription, nothing to tear down.
INV-2026-0184
in Invoices · 5 levels deep
The heading and the crumbs are two readings of the same signal. Only the trail changes when you move; neither the header nor the component is told anything.
Code
Import:
Template:
Component:
Dynamic Content
Dynamic breadcrumb content resolution from route data and resolvers with placeholder support.
Examples:
Dynamic Breadcrumbs
Labels built from a route placeholder and the data its resolver returns.
Dynamic Breadcrumbs
Labels built from a route placeholder and the data its resolver returns.
The last crumb comes from a route declaring breadcrumb: "Dynamic: {name}", resolved with that route's data. This page has no router tree, so the demo is handed the resulting trail — the route configuration is in the TS tab.
Code
Code
Import:
Template:
Component:
Templates & Customization
Rich customization options with custom templates for breadcrumb items and enhanced styling.
Examples:
Custom Templates
Take over the markup of every crumb with the hubBreadcrumbItem template.
Custom Templates
Take over the markup of every crumb with the hubBreadcrumbItem template.
The hubBreadcrumbItem directive allows custom rendering of each element.
Code
Code
Import:
Template:
Component:
Advanced Features
Enhanced functionality including icon support, RTL layout compatibility, collapsing for long trails and a tokenized keyboard focus ring.
Examples:
Icons on the Trail
Icons declared in the route data, rendered through a custom item template.
Icons on the Trail
Icons declared in the route data, rendered through a custom item template.
Code
Code
Import:
Template:
Component:
RTL Layout
Right-to-left support, with the separator on the side the trail comes from.
RTL Layout
Right-to-left support, with the separator on the side the trail comes from.
Code
Code
Import:
Template:
Component:
Truncation & Tooltip
Clip a long label with an ellipsis and reveal its full text on hover.
Truncation & Tooltip
Clip a long label with an ellipsis and reveal its full text on hover.
Each label is capped at --hub-breadcrumb-max-item-width (12rem). Only the items that overflow get a tooltip.
Code
Code
Import:
Template:
Component:
Collapsing Long Trails
Fold the middle of a deep trail behind an indicator button that expands it in place.
Six crumbs, no collapsing — the default
maxItems = 4 — one crumb each side of the indicator
maxItems = 4 with two crumbs kept on each side
Indicator opened 0 time(s) — that is the collapsedClick output. The trail expands on its own and collapses again on the next navigation.
Code
Import:
Template:
Component:
Keyboard Focus Ring
The design-system focus ring on links and on the collapsed indicator, re-tintable through CSS variables.
Default ring — press Tab to walk the trail
Re-tinted ring on the same markup
The ring reaches the collapsed indicator too, which is a button and therefore part of the tab order. Note where the overrides live: the focus tokens are declared on :host, so a value set on an ancestor never reaches them — put it on the <hub-breadcrumb> element or inside it. (The accent slot is the one exception, left undeclared on purpose so it does inherit.)
Code
Import:
Template:
Component:
Key features
Recent changes
Version 22.6.0 - 9/6/26, 12:00 AM
added: HubBreadcrumbsService.breadcrumbs exposes the trail as a signal. The service published only an Observable, so every consumer inside a signal-based component repeated the same toSignal(svc.breadcrumbs$, { initialValue: [] }) wrapper, the component in this library included. The wrapping now happens once inside the service, which also subscribes the route tree once for the whole application instead of once per breadcrumb on screen. breadcrumbs$ stays exactly as it was for code that composes with rxjs.
changed: HubBreadcrumbComponent no longer re-exports breadcrumbs$. The component carried the Observable of the service as a public field and a signal derived from it, so a single trail had two public surfaces on the same class and neither was the one the template rendered. It now reads HubBreadcrumbsService.breadcrumbs directly: anyone who was reading the field can inject the service, which is where the trail came from anyway, and anyone substituting the service must publish breadcrumbs. See BREAKING_CHANGES.md.
fixed: Opening a collapsed trail from the keyboard no longer leaves focus on the page body. Expanding removes the ellipsis indicator the reader just activated, and the browser answers that by focusing the body, so someone who had pressed Enter had to tab from the top of the page to reach the crumbs they asked for. Focus is now handed to the first crumb the gesture reveals, the one at itemsBeforeCollapse, which takes it through a temporary tabindex of -1 when it renders as plain text. Consumers who moved focus by hand in (collapsedClick) can drop that code.
fixed: The current crumb is announced as the current page even when the consumer renders it. aria-current="page" sat on the default span, the one branch a hubBreadcrumbItem template replaces, so a trail with a custom template reached assistive technology with nothing marking the current page while the docs promised the attribute unqualified. It now sits on the li, which wraps every branch. The attribute moved: a stylesheet or a test selecting .hub-breadcrumb__text[aria-current] should read .hub-breadcrumb__item[aria-current], while the hub-breadcrumb__item--active modifier is unchanged and is still the styling hook.
fixed: --hub-breadcrumb-accent set from the application reaches the component again. The slot was declared on :host, which under emulated encapsulation is a [_nghost] rule on the crumb element itself, so a consumer rule on hub-breadcrumb lost, one on .hub-breadcrumb tied and lost on source order, and a value inherited from an ancestor, the hub-breadcrumb-theme() mixin included, never reached the links at all. The slot is no longer declared on the host: it is read where it is consumed, as var(--hub-breadcrumb-accent, var(--hub-sys-color-primary, #0d6efd)), so the default look is byte-identical, variant still wins over a consumer rule, and a plain tag or class rule, or any ancestor, now recolours the links and everything derived from them. The remaining --hub-breadcrumb-* defaults still live on :host, so overriding those still means the crumb element itself or .hub-breadcrumb__list.
fixed: The built-in variant list in the component names the same nine accents its stylesheet emits. 22.2.0 grew the accent set from five to nine in the SCSS loop, but BUILT_IN_VARIANTS was left at the original five, so secondary, neutral, light and dark were treated as custom accents and got an inline --hub-breadcrumb-accent on the host on top of the stylesheet rule that already set them. Nothing rendered differently, since both paths resolve to the same token, but an inline style outranks anything a consumer writes in a sheet, so overriding the accent for those four took an !important it should never have needed. The variant JSDoc listed the same stale five and now names all nine.
fixed: The documentation described an API this library does not have, and taught a mixin selector that does not win. The README opened its reference announcing a single optional input above a table of seven inputs and one output, listed five built-in variants against the nine the stylesheet emits, never named HubBreadcrumbLabelDirective or the tooltip adapter contract although both are exported, promised truncation without saying that a hubBreadcrumbItem template renders its own elements, which the scoped styles cannot reach, so they get neither the ellipsis nor the tooltip, and still announced v21.1.0 as the latest release. The hub-breadcrumb-theme() snippet included the mixin on a bare class, which ties with :host and loses on source order, and now lands on the crumb element with a selector that outranks it. BREAKING_CHANGES.md was titled after v21.1.0 over a 22.4.0 section, FUNCTIONALITIES.md marked (collapsedClick) and the tooltip adapter as uncovered while the examples exercise both, and docs/css-variables-reference.md referenced the three derived accent tokens without documenting any of them. Documentation only, with no change to code, types or styles.
deprecated: HubBreadcrumbsModule is deprecated and will be removed in 23.0.0. It imports and exports HubBreadcrumbComponent and HubBreadcrumbItemDirective, both standalone and both already exported from the entry point, and provides nothing of its own, so importing them directly is the whole migration. HubBreadcrumbsService is providedIn: root and never travelled through the module. The class carried no @deprecated tag until now, so neither an editor nor the build could warn anyone. See BREAKING_CHANGES.md.
Version 22.5.2 - 9/2/26, 12:00 AM
fixed: A breadcrumb asked for before the first navigation no longer throws. breadcrumbs$ opens with startWith(undefined), so the route tree is walked the moment anything subscribes, and a page shell that draws its breadcrumb on the first paint subscribes while the initial navigation is still in flight. In that window a child route exists with no snapshot and child.snapshot.url threw — into the subscription drawing the shell, so what a consumer saw was the whole header gone rather than a missing breadcrumb. A route with no snapshot is skipped rather than guessed at: it has no segments and no resolved data, so there is nothing to name yet. Present in every release from 21.0.0 onwards.
Version 22.5.1 - 9/1/26, 12:00 AM
changed: The homepage in the manifest points at this library's own documentation page rather than at the site root. Metadata only.
Version 22.5.0 - 8/29/26, 12:00 AM
added: Collapsing for long trails: `maxItems`, `itemsBeforeCollapse` and `itemsAfterCollapse` fold the middle behind an indicator button that expands in place and emits `collapsedClick`.
added: Crumbs can point outside the router: `href`, `target`, `rel` and `download` on `BreadcrumbItem`, accepted both from the new object form of `data.breadcrumb` and from the new `items` input. A `_blank` crumb defaults to `rel="noopener noreferrer"`.
added: Keyboard focus ring on links and on the collapsed indicator, built on the design-system focus tokens and exposed as `--hub-breadcrumb-focus-*` / `--hub-breadcrumb-link-focus-color`.
changed: `BreadcrumbItem` and `BreadcrumbTemplateContext` are now exported from the public API, and `BreadcrumbItem.data` became optional.
Version 22.4.3 - 8/17/26, 12:00 AM
fixed: The package shipped without its licence notice. package.json declared MIT, but no LICENSE file travelled in the tarball — and MIT itself requires the copyright notice to be included in distributions. The notice ships now.
Version 22.4.2 - 8/8/26, 12:00 AM
fixed: Documentation links now point at the canonical localized URLs. The README linked to https://hubui.dev/<path> with no locale prefix and no trailing slash, and both forms are 301-redirected, so every reader arriving from npm or GitHub landed on a redirect instead of the canonical page.
Version 22.4.1 - 7/28/26, 12:00 AM
fixed: The active (last) crumb now declares aria-current=page so assistive technology announces the current position.
Version 22.4.0 - 7/7/26, 12:00 AM
changed: BREAKING (packaging) — the SCSS ships at ng-hub-ui-breadcrumbs/styles. The theme mixin now builds to dist/breadcrumbs/styles/… instead of dist/breadcrumbs/src/lib/styles/…, so @use 'ng-hub-ui-breadcrumbs/styles' resolves. Any @use that reached into src/lib/styles has to be updated.
Version 22.3.1 - 7/6/26, 12:00 AM
fixed: Docs: the default values in docs/css-variables-reference.md were resynchronized with the actual declarations (--hub-breadcrumb-item-padding-x, --hub-breadcrumb-accent, --hub-breadcrumb-link-hover-color), now guarded by the repo-level tokens-parity check.
Version 22.3.0 - 6/29/26, 12:00 AM
added: Opt-in per-item truncation via the `truncateItems` input + `--hub-breadcrumb-max-item-width`.
added: `HubBreadcrumbLabelDirective` showing a tooltip only when a label overflows.
added: Optional hub-ui tooltip integration via `provideHubBreadcrumbTooltip(hubTooltipAdapter)` (native `title` fallback).
Version 22.2.0 - 6/26/26, 12:00 AM
changed: The accent moved to the open-set "local accent slot" pattern: variant re-bases a single --hub-breadcrumb-accent and the link hover is derived locally as --hub-breadcrumb-accent-emphasis with color-mix, mirroring the ds engine. The built-in list grew from five accents to the nine canonical ones (primary · secondary · success · danger · warning · info · neutral · light · dark), and a bare [data-variant] block re-derives the family from the slot, so any custom accent the host app adds recolours the links with one CSS rule and no recompilation.
added: Tokens --hub-breadcrumb-accent-emphasis (link hover), --hub-breadcrumb-accent-subtle and --hub-breadcrumb-accent-on, all derived locally from the accent slot.
Version 22.1.2 - 6/26/26, 12:00 AM
fixed: The Angular peer dependency range was corrected to >=18.0.0. The library uses APIs whose real minimum is Angular 17.3, so the previous >=17.0.0 range let it install on incompatible versions.
Version 22.1.1 - 6/25/26, 12:00 AM
fixed: Design-token consistency pass: inline fallback defaults aligned with the canonical ng-hub-ui-ds values, and hardcoded literals (z-index, font-weight, line-height, radii, theme-aware colours) routed through their --hub-sys-* / --hub-ref-* tokens so they follow the active theme. No visual change when the ds tokens are loaded.
Version 22.1.0 - 6/24/26, 12:00 AM
added: The variant input on <hub-breadcrumb>, selecting a semantic accent for the links and their hover while the current item stays muted. Any string outside the built-in set is also accepted and read as --hub-sys-color-<variant>. New token --hub-breadcrumb-accent.
added: The hub-breadcrumb-theme() Sass mixin — surface, spacing, divider, current-item colour, links and accent in one call. Every parameter is optional, so only the ones passed are emitted as --hub-breadcrumb-* overrides.
Version 22.0.0 - 6/17/26, 12:00 AM
changed: Aligned with Angular 22, and the README standardized.
Version 21.1.0 - 3/17/26, 12:00 AM
changed: The selector was renamed from hub-breadcrumbs to hub-breadcrumb, and the styles are bundled within the component — a manual style import is no longer required.
Version 21.0.0 - 3/9/26, 12:00 AM
changed: BREAKING — the service, module, components and directives were renamed for consistency across the library family.