Angular Breadcrumbs Component | ng-hub-ui-breadcrumbs

Angular breadcrumbs component with router integration, custom templates, RTL support and flexible styling tokens.

Last updated Sep 28, 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-breadcrumbs

Jump 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, llms.txt downloads a file, and Design system 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.10.1 - 9/28/26, 12:00 AM

changed: The family list in both READMEs names `ng-hub-ui-spreadsheet`. The sheet joined the family and the other lists had not caught up. Documentation only: no code, types or styles change.

Version 22.10.0 - 9/23/26, 12:00 AM

changed: BREAKING: the Angular floor rises from 17.2.0 to 17.3.0. The old range was measured from the source alone, and its published `.d.ts` names `InputSignalWithTransform` or `OutputEmitterRef`, which Angular did not ship until 17.3. An application below the new floor could install this package and then fail to build; it now gets the peer warning it should always have had. Nothing that worked stops working. See BREAKING_CHANGES.md.

Version 22.9.1 - 9/23/26, 12:00 AM

changed: The Angular peer range now says what the code needs. It asked for >=19.0.0, which nothing in this package justified: the newest Angular API the source uses is the signal queries, which shipped in 17.2, and the compiled output carries no linker marker above it. The range is >=17.2.0, and npm run peers:floors derives and checks that floor from now on.

Version 22.9.0 - 9/21/26, 12:00 AM

added: A crumb can have no destination. url is optional, and a crumb declaring neither url nor href renders as plain text, the way the last crumb always has. Some levels of a trail name a grouping rather than a page, and until now they had to be pointed at a route that does not exist.

Version 22.8.0 - 9/21/26, 12:00 AM

changed: The declared Angular floor moves to 19, which is the version the code can actually run on: the manifest asked for 18 while the component builds its expanded state with linkedSignal, introduced in Angular 19. @angular/router is now declared as a peer dependency too, since the service injects Router and ActivatedRoute and the crumbs render as routerLink.

Version 22.7.3 - 9/20/26, 12:00 AM

changed: The npm keywords declare ng-hub-ui and hub-ui, the family names, and add router, ui-component, angular-library, standalone and accessibility. Metadata only: no code, types or styles change.

Version 22.7.2 - 9/16/26, 12:00 AM

changed: Repository, issue and README links follow the move to the hub-env organization. Issues for every Hub UI package are now gathered in hub-env/hub-ui, and the repository and bugs fields of the manifest point at the new addresses. No code, types or styles change.

Version 22.7.1 - 9/8/26, 12:00 AM

added: ng-hub-ui-ds is declared as an optional peer dependency (>=22.0.0). Every --hub-breadcrumb-* default resolves through the family --hub-sys-* / --hub-ref-* ladder, which is what makes the trail match a theme and its dark mode before anything is overridden, and the manifest said nothing about it, so a consumer reading the package on npm could not tell which package supplies those values. It is genuinely optional: every token ends in a literal fallback.

Version 22.7.0 - 9/7/26, 12:00 AM

fixed: truncateItems now clips a crumb rendered by a hubBreadcrumbItem template. The clipping rules named only the classes the component draws, and the elements a custom template renders belong to the consuming component, where a scoped rule cannot reach them, so a consumer who had personalised the markup set the input and got nothing at all, in silence. The component now draws the clipping box itself, a span.hub-breadcrumb__custom around the projected content, sitting inside the item and outside the separator so a custom crumb gets exactly the width a built-in one gets.

changed: A custom crumb gets the overflow tooltip too: the new box carries hubBreadcrumbLabel, so the full text of a clipped custom label is exposed the way a built-in one is. Applying the directive by hand inside the template is no longer needed, and is now only for overriding the tooltip text. The crumb does render one element deeper, so a selector written against the old shape has to be adjusted: see BREAKING_CHANGES.md.

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.

Related libraries

ng-hub-ui-nav ng-hub-ui-utils ng-hub-ui-portal

Frequently asked questions

How do I add breadcrumbs to an Angular application?

Put <hub-breadcrumb /> in the layout and add data: { breadcrumb: 'Products' } to the routes that should appear. The component reads the active route tree and builds the trail itself, inside a nav labelled breadcrumb, with aria-current=page on the last crumb. To drive it by hand instead, pass the items input and the router-derived trail steps aside.

How do I shorten a long breadcrumb trail?

maxItems collapses the middle behind a real button, and itemsBeforeCollapse and itemsAfterCollapse decide how many crumbs stay at each end; expanding it emits collapsedClick and moves focus to the first crumb revealed. truncateItems is the other half: it caps each label at --hub-breadcrumb-max-item-width, 12rem by default, and shows the whole text on hover, through ng-hub-ui-utils when you register its tooltip adapter and through the plain title attribute when you do not.

How do I change the separator between breadcrumbs?

Not with an input. The divider is drawn in CSS from --hub-breadcrumb-divider, which defaults to a greater-than sign, and --hub-breadcrumb-divider-flipped covers right-to-left layouts. What a crumb itself looks like is yours through the *hubBreadcrumbItem template, which receives the item and its position, and hubBreadcrumbLabel marks the text that may be truncated.

Does it work without the Angular router?

No. The service injects Router and ActivatedRoute and the crumbs render as routerLink, so a router-less application cannot use the package. Two limits of the automatic trail are worth knowing before you rely on it: only routes that declare data.breadcrumb on their own configuration are picked up, and the walk follows the first child at each level, so sibling and auxiliary outlets are skipped. Pass items yourself when the trail does not match the route tree.