gog-breadcrumbs

Breadcrumbs 21.18.0

Where the current page sits, as a trail of your own links. Every part of a correct trail is invisible — the named landmark, the list, aria-current="page" on the last item, separators a screen reader does not read — so nothing on screen says when a hand-built one is missing them. The links stay yours: routerLink, href and anything else on them keep working.

Overview

import { BreadcrumbsComponent, GogBreadcrumbDirective } from '@guildofgleks/ui';

@Component({
  // ...
  imports: [BreadcrumbsComponent, GogBreadcrumbDirective],
})

Mark each item with the structural *gogBreadcrumb directive. The last item is the current page — usually a <span>, since it does not link anywhere:

<gog-breadcrumbs>
  <a *gogBreadcrumb routerLink="/">Home</a>
  <a *gogBreadcrumb routerLink="/components/breadcrumbs">Components</a>
  <span *gogBreadcrumb>Breadcrumbs</span>
</gog-breadcrumbs>

Examples

Sizes

Five text steps. The parents are links in the muted colour, the current page is the text colour and semibold; hover a link for the underline, Tab to it for the ring.

xsm

slg

@for (size of sizes; track size) {
  <div>
    <span>{{ size }}</span>
    <gog-breadcrumbs [size]="size">
      <a *gogBreadcrumb routerLink="/">Home</a>
      <a *gogBreadcrumb routerLink="/components/breadcrumbs">Components</a>
      <span *gogBreadcrumb>Breadcrumbs</span>
    </gog-breadcrumbs>
  </div>
}

Collapsing a long trail

Past maxItems the middle becomes a … button; itemsBefore and itemsAfter say how many stay either side (one and two by default — the current page and its parent). Press the … from the keyboard: the button is removed by its own press, so focus moves to the first link it revealed rather than falling to <body>. A trail that would hide nothing does not collapse.

maxItems unset

[maxItems]="4"

itemsBefore 2, after 1

<div>
  <span>maxItems unset</span>
  <gog-breadcrumbs>
    @for (crumb of trail; track crumb; let last = $last) {
      @if (last) {
        <span *gogBreadcrumb>{{ crumb }}</span>
      } @else {
        <a *gogBreadcrumb routerLink="/components/breadcrumbs">{{ crumb }}</a>
      }
    }
  </gog-breadcrumbs>
</div>
<div>
  <span>[maxItems]="4"</span>
  <gog-breadcrumbs [maxItems]="4">
    @for (crumb of trail; track crumb; let last = $last) {
      @if (last) {
        <span *gogBreadcrumb>{{ crumb }}</span>
      } @else {
        <a *gogBreadcrumb routerLink="/components/breadcrumbs">{{ crumb }}</a>
      }
    }
  </gog-breadcrumbs>
</div>
<div>
  <span>itemsBefore 2, after 1</span>
  <gog-breadcrumbs [maxItems]="4" [itemsBefore]="2" [itemsAfter]="1">
    @for (crumb of trail; track crumb; let last = $last) {
      @if (last) {
        <span *gogBreadcrumb>{{ crumb }}</span>
      } @else {
        <a *gogBreadcrumb routerLink="/components/breadcrumbs">{{ crumb }}</a>
      }
    }
  </gog-breadcrumbs>
</div>

separatorIcon

Any icon name, built-in or registered with provideGogIcons. It is drawn, not written, so it never reaches a screen reader.

<gog-breadcrumbs separatorIcon="arrow-right">
  <a *gogBreadcrumb routerLink="/">Home</a>
  <a *gogBreadcrumb routerLink="/general/getting-started">Docs</a>
  <span *gogBreadcrumb>Install</span>
</gog-breadcrumbs>

Right to left

The separator points from a parent to its child, which is leftwards under dir="rtl". Nothing to set — the trail reads the direction it is in.

<div dir="rtl">
  <gog-breadcrumbs>
    <a *gogBreadcrumb routerLink="/">Home</a>
    <a *gogBreadcrumb routerLink="/general/getting-started">Docs</a>
    <span *gogBreadcrumb>Install</span>
  </gog-breadcrumbs>
</div>

A narrow container

A long trail wraps between items rather than overflowing; maxItems is the answer when it should stay on one line.

<div style="max-width: 16rem">
  <gog-breadcrumbs>
    @for (crumb of trail; track crumb; let last = $last) {
      @if (last) {
        <span *gogBreadcrumb>{{ crumb }}</span>
      } @else {
        <a *gogBreadcrumb routerLink="/components/breadcrumbs">{{ crumb }}</a>
      }
    }
  </gog-breadcrumbs>
</div>

Accessibility

A trail a screen reader can use is mostly structure that nothing on screen shows.

Landmark — a <nav> named "Breadcrumb", from ariaLabel or GOG_CONFIG.labels.breadcrumbs, so it appears in a screen reader's landmark list beside the main navigation.
List — an ordered list, one <li> per item, so the reader hears how many levels deep the page is.
Current page — the trail sets aria-current="page" on your last element, and moves it when the last item changes. Leave it out of the link: a link to the page you are on is a dead end.
Separators — aria-hidden; "chevron" between every word is noise.
The … button — a real button named "Show full path" (GOG_CONFIG.labels.showBreadcrumbs), and focus moves to what it revealed.

API Reference

gog-breadcrumbs inputs

Name	Type	Default	Description
`maxItems`	`number \| null`	`null`	Past this many items the middle collapses into a … button. Unset, the trail never collapses.
`itemsBefore`	`number`	`1`	Items kept before the … while collapsed.
`itemsAfter`	`number`	`2`	Items kept after it — the current page and its parent.
`separatorIcon`	`GogIconName`	`'chevron-right'`	Drawn between items, and mirrored under dir="rtl".
`size`	`GogSize`	`'md'`	'xsm' \| 'sm' \| 'md' \| 'lg' \| 'slg'.
`ariaLabel`	`string \| undefined`	`undefined`	Names the landmark. Unset, GOG_CONFIG.labels.breadcrumbs, then "Breadcrumb".

Directives

Selector	Goes on	Description
`*gogBreadcrumb`	`your <a> or <span>`	One item. Structural, so the trail receives a template and can stamp each item in its own <li> and leave the middle out while collapsed; the element stays yours.

Global Configuration

Set any of these once with provideGogConfig() instead of repeating them on every instance — an instance's own input still wins when it sets one itself. See Global Configuration for the full reference.

GOG_CONFIG.labels.breadcrumbs — the landmark’s name, unless ariaLabel is set
GOG_CONFIG.labels.showBreadcrumbs — the … button of a collapsed trail

Styling Tokens

Every CSS custom property the breadcrumbs paints with. Override any of them — on a single instance, a subtree, or a theme — to restyle it. See the Theming guide for the full token-layering model, or the Theme Generator to tweak these live.

Token	Description
`--gog-breadcrumbs-font-family / -line-height / -gap`	The trail’s typeface, its leading, and the space either side of a separator.
`--gog-breadcrumbs-xsm-font-size / -sm-font-size / -md-font-size / -lg-font-size / -slg-font-size`	The text at each size; the separator glyph is drawn from it.
`--gog-breadcrumbs-link-color / -link-hover-color`	A parent link, at rest and under the pointer.
`--gog-breadcrumbs-current-color / -current-font-weight`	The last item — the current page, which is not a link.
`--gog-breadcrumbs-separator-color`	The separator icon between items. Decorative and hidden from assistive tech.
`--gog-breadcrumbs-more-padding-y / -more-padding-x / -more-radius / -more-hover-bg`	The … button a collapsed trail draws in place of its middle.
`--gog-breadcrumbs-focus-ring-width / -focus-ring-offset / -focus-ring-color`	The keyboard focus ring on a link and on the … button.