Surfaces

Stable - @kikita-labs/ui v2.0.0

Breadcrumbs

Hierarchy trails built from native navigation, lists, links, and current-page text.

Import

Breadcrumbs use directives on native list, link, and text elements.

breadcrumbs.ts
import {
  KuiBreadcrumbItem,
  KuiBreadcrumbSeparator,
  KuiBreadcrumbs,
} from '@kikita-labs/ui';

Usage

Open in Playground

Wrap the ordered list in a labelled navigation landmark and mark the final crumb as current.

<nav class="basic-breadcrumbs-example" aria-label="Breadcrumb">
  <ol kuiBreadcrumbs>
    <li><a kuiBreadcrumbItem href="/components">Components</a></li>
    <li kuiBreadcrumbSeparator></li>
    <li><span kuiBreadcrumbItem>Surfaces</span></li>
    <li kuiBreadcrumbSeparator></li>
    <li><span kuiBreadcrumbItem current>Breadcrumbs</span></li>
  </ol>
</nav>

Plain-text crumbs

Use a span without current for a grouping crumb that has no page of its own, as the middle crumb in the first example does. Only the last crumb carries current.

  • A span[kuiBreadcrumbItem] without current is plain text and is not focusable.
  • current is meaningful on a span only and sets aria-current="page".
  • An optional leading icon goes on the first crumb only, inside a span.kui-breadcrumb-icon.

Sizes

size scales the font, separators and spacing of the whole trail.

<div class="breadcrumbs-size-example">
  <nav aria-label="Small breadcrumb">
    <ol kuiBreadcrumbs size="sm">
      <li><a kuiBreadcrumbItem href="/components">Components</a></li>
      <li kuiBreadcrumbSeparator></li>
      <li><span kuiBreadcrumbItem current>Small</span></li>
    </ol>
  </nav>

  <nav aria-label="Medium breadcrumb">
    <ol kuiBreadcrumbs>
      <li><a kuiBreadcrumbItem href="/components">Components</a></li>
      <li kuiBreadcrumbSeparator></li>
      <li><span kuiBreadcrumbItem current>Medium</span></li>
    </ol>
  </nav>

  <nav aria-label="Large breadcrumb">
    <ol kuiBreadcrumbs size="lg">
      <li><a kuiBreadcrumbItem href="/components">Components</a></li>
      <li kuiBreadcrumbSeparator></li>
      <li><span kuiBreadcrumbItem current>Large</span></li>
    </ol>
  </nav>
</div>

Narrow screens

The library does not enforce one collapse strategy. Truncate a middle crumb with .kui-breadcrumb-truncate on a non-wrapping trail, collapse hidden levels behind an ellipsis button wired to a kui-menu, or keep only the first and last crumbs at the narrowest breakpoint.

<div class="breadcrumbs-collapse-example">
  <nav aria-label="Truncated breadcrumb">
    <ol kuiBreadcrumbs class="breadcrumbs-collapse-example__trail">
      <li><a kuiBreadcrumbItem href="#catalog">Catalog</a></li>
      <li kuiBreadcrumbSeparator></li>
      <li>
        <a kuiBreadcrumbItem class="kui-breadcrumb-truncate" href="#audio">
          Audio equipment and accessories
        </a>
      </li>
      <li kuiBreadcrumbSeparator></li>
      <li><span kuiBreadcrumbItem current>Headphones</span></li>
    </ol>
  </nav>

  <nav aria-label="Collapsed breadcrumb">
    <ol kuiBreadcrumbs>
      <li><a kuiBreadcrumbItem href="#catalog">Catalog</a></li>
      <li kuiBreadcrumbSeparator></li>
      <li>
        <button
          class="kui-breadcrumb-ellipsis"
          type="button"
          aria-label="Show hidden levels"
          [kuiMenuFor]="hiddenLevels"
        >
          &hellip;
        </button>
      </li>
      <li kuiBreadcrumbSeparator></li>
      <li><span kuiBreadcrumbItem current>Headphones</span></li>
    </ol>
  </nav>

  <kui-menu #hiddenLevels ariaLabel="Hidden levels">
    <a kuiMenuItem href="#electronics">Electronics</a>
    <a kuiMenuItem href="#audio">Audio</a>
  </kui-menu>
</div>

Provider defaults

Set defaults.breadcrumbs once for the application or for a subtree. Each option resolves as local input > defaults.breadcrumbs.<option> > built-in default.

import { provideKikitaUi } from '@kikita-labs/ui';

export const appConfig: ApplicationConfig = {
  providers: [
    provideKikitaUi({
      defaults: {
        breadcrumbs: {
          /* options below */
        },
      },
    }),
  ],
};
NameTypeDefaultDescription
size'sm' | 'md' | 'lg' — Component size. Takes precedence over the global defaults.size.
separatorIconKuiIconGlyph — Icon between crumbs. Takes precedence over defaults.icons.separator. See Structural Icons.

Theming tokens

Set any of these on the component or an ancestor to restyle one part. Each token is optional: when it is not set, the part uses the role or scale token in the default column.

NameTypeDefaultDescription
--kui-breadcrumb-link-focus-ring-colorCSS custom property--kui-color-focusLink focus ring color
--kui-breadcrumb-sep-colorCSS custom property--kui-color-text-secondarySep color
--kui-breadcrumb-ellipsis-colorCSS custom property--kui-color-text-secondaryEllipsis color
--kui-breadcrumb-ellipsis-bg-hoverCSS custom property--kui-color-surface-elevatedEllipsis background, hover
--kui-breadcrumb-ellipsis-color-hoverCSS custom property--kui-color-textEllipsis color, hover
NameTypeDefaultDescription
--kui-breadcrumb-font-sizeCSS custom property--kui-text-sm-sizeFont size
--kui-breadcrumb-link-radiusCSS custom property--kui-radius-smLink corner radius
--kui-breadcrumb-link-gapCSS custom property--kui-space-1Link gap
--kui-breadcrumb-plain-gapCSS custom property--kui-space-1Plain gap
--kui-breadcrumb-current-gapCSS custom property--kui-space-1Current gap
--kui-breadcrumb-ellipsis-padding-inlineCSS custom property--kui-space-1Ellipsis padding, inline
--kui-breadcrumb-ellipsis-radiusCSS custom property--kui-radius-smEllipsis corner radius
--kui-breadcrumb-font-size-smCSS custom property--kui-text-xs-sizeFont size, sm
--kui-breadcrumb-font-size-lgCSS custom property--kui-text-md-sizeFont size, lg
--kui-breadcrumb-ellipsis-heightCSS custom property22pxEllipsis button height
--kui-breadcrumb-ellipsis-height-smCSS custom property18pxEllipsis button height, sm
--kui-breadcrumb-ellipsis-height-lgCSS custom property26pxEllipsis button height, lg
--kui-breadcrumb-icon-size-smCSS custom property12pxSeparator and icon size, sm
--kui-breadcrumb-icon-size-lgCSS custom property16pxSeparator and icon size, lg
--kui-breadcrumb-truncate-max-widthCSS custom property140pxMaximum width of a truncated item

API

Inputs verified against @kikita-labs/ui v2.0.0 public typings.

NameTypeDefaultDescription
ol[kuiBreadcrumbs].size'sm' | 'md' | 'lg''md'Font size, separator scale, and spacing for the full trail. Falls back to defaults.breadcrumbs.size, then the global defaults.size.
a[kuiBreadcrumbItem]directive-Native link crumb for navigable hierarchy levels.
span[kuiBreadcrumbItem]directive-Plain-text crumb for grouping labels or the current page.
span[kuiBreadcrumbItem].currentbooleanfalseMarks the final crumb as the current page and sets aria-current.
li[kuiBreadcrumbSeparator]component-Decorative separator list item hidden from assistive technology.
.kui-breadcrumb-truncateCSS class-Added to the crumb that should shrink with an ellipsis; keep the trail non-wrapping. The maximum width is --kui-breadcrumb-truncate-max-width.
button.kui-breadcrumb-ellipsisCSS class-Styles a button that stands in for hidden crumbs. Breadcrumbs does not manage the menu; wire it to kui-menu or kui-dropdown yourself.
span.kui-breadcrumb-iconCSS class-Optional leading icon wrapper, on the first crumb only.
KuiBreadcrumbsOptionsinterface-Shape of defaults.breadcrumbs: size and separatorIcon (takes precedence over defaults.icons.separator).

Accessibility

The component keeps native semantics visible instead of replacing navigation with custom widgets.

  • Use <nav aria-label="Breadcrumb"> around the trail.
  • Keep navigable ancestors as native links.
  • Render the current page as non-focusable text with current.
  • Collapse long mobile trails with first/last crumbs or a separate menu pattern.
  • Breadcrumb links intentionally do not compose kuiLink: breadcrumbs own their navigation spacing, size scale, tokens and current-page treatment. Keep navigable crumbs as native anchors with kuiBreadcrumbItem.
  • The ellipsis button needs an accessible name (for example aria-label) and opens a menu that lists the hidden levels.

Migrating to 2.0

Consumer-visible changes of @kikita-labs/ui 2.0 for Breadcrumbs.

  • The classes are KuiBreadcrumbs, KuiBreadcrumbItem and KuiBreadcrumbSeparator (they had a Directive or Component suffix). ng update @kikita-labs/ui renames the imports.
  • The default size comes from defaults.breadcrumbs.size and the separator icon from defaults.breadcrumbs.separatorIcon (it takes precedence over defaults.icons.separator).
  • The ellipsis, separator and truncation sizes are geometry tokens, and the focus ring is the shared 2px outline.