Skip to content
WebJs
Menu

Displays the path to the current resource using a hierarchy of links.

import { html } from '@webjsdev/core';
import { buttonClass } from '#components/ui/button.ts';
import {
  breadcrumbListClass, breadcrumbItemClass, breadcrumbLinkClass, breadcrumbPageClass,
  breadcrumbSeparatorClass, breadcrumbEllipsisClass,
} from '#components/ui/breadcrumb.ts';
import { ChevronRightIcon, MoreHorizontalIcon } from '#lib/ui/lucide.ts';

const separator = () => html`
  <li data-slot="breadcrumb-separator" role="presentation" aria-hidden="true" class=${breadcrumbSeparatorClass()}>${ChevronRightIcon('cn-rtl-flip')}</li>
`;

export default function BreadcrumbDemo() {
  return html`
    <nav aria-label="breadcrumb" data-slot="breadcrumb">
      <ol data-slot="breadcrumb-list" class=${breadcrumbListClass()}>
        <li data-slot="breadcrumb-item" class=${breadcrumbItemClass()}>
          <a data-slot="breadcrumb-link" href="#" class=${breadcrumbLinkClass()}>Home</a>
        </li>
        ${separator()}
        <li data-slot="breadcrumb-item" class=${breadcrumbItemClass()}>
          <ui-dropdown-menu>
            <ui-dropdown-menu-trigger>
              <button type="button" data-slot="button" data-variant="ghost" data-size="icon-sm" class=${buttonClass({ variant: 'ghost', size: 'icon-sm' })}>
                <span data-slot="breadcrumb-ellipsis" role="presentation" aria-hidden="true" class=${breadcrumbEllipsisClass()}>
                  ${MoreHorizontalIcon()}
                  <span class="sr-only">More</span>
                </span>
                <span class="sr-only">Toggle menu</span>
              </button>
            </ui-dropdown-menu-trigger>
            <ui-dropdown-menu-content align="start">
              <ui-dropdown-menu-group>
                <ui-dropdown-menu-item>Documentation</ui-dropdown-menu-item>
                <ui-dropdown-menu-item>Themes</ui-dropdown-menu-item>
                <ui-dropdown-menu-item>GitHub</ui-dropdown-menu-item>
              </ui-dropdown-menu-group>
            </ui-dropdown-menu-content>
          </ui-dropdown-menu>
        </li>
        ${separator()}
        <li data-slot="breadcrumb-item" class=${breadcrumbItemClass()}>
          <a data-slot="breadcrumb-link" href="#" class=${breadcrumbLinkClass()}>Components</a>
        </li>
        ${separator()}
        <li data-slot="breadcrumb-item" class=${breadcrumbItemClass()}>
          <span data-slot="breadcrumb-page" role="link" aria-disabled="true" aria-current="page" class=${breadcrumbPageClass()}>Breadcrumb</span>
        </li>
      </ol>
    </nav>
  `;
}
View Code

Installation

pnpm dlx @webjsdev/ui add breadcrumb

Usage

import {
  breadcrumbListClass,
  breadcrumbItemClass,
  breadcrumbLinkClass,
  breadcrumbPageClass,
  breadcrumbSeparatorClass,
} from '#components/ui/breadcrumb.ts';
<nav aria-label="breadcrumb" data-slot="breadcrumb">
  <ol data-slot="breadcrumb-list" class=${breadcrumbListClass()}>
    <li data-slot="breadcrumb-item" class=${breadcrumbItemClass()}>
      <a data-slot="breadcrumb-link" href="/" class=${breadcrumbLinkClass()}>Home</a>
    </li>
    <li data-slot="breadcrumb-separator" role="presentation" aria-hidden="true" class=${breadcrumbSeparatorClass()}>
      ${ChevronRightIcon()}
    </li>
    <li data-slot="breadcrumb-item" class=${breadcrumbItemClass()}>
      <a data-slot="breadcrumb-link" href="/components" class=${breadcrumbLinkClass()}>Components</a>
    </li>
    <li data-slot="breadcrumb-separator" role="presentation" aria-hidden="true" class=${breadcrumbSeparatorClass()}>
      ${ChevronRightIcon()}
    </li>
    <li data-slot="breadcrumb-item" class=${breadcrumbItemClass()}>
      <span data-slot="breadcrumb-page" aria-current="page" class=${breadcrumbPageClass()}>Breadcrumb</span>
    </li>
  </ol>
</nav>

Composition

Use the following composition to build a breadcrumb:

<nav aria-label="breadcrumb">
└── breadcrumbListClass()
    ├── breadcrumbItemClass()
    │   └── breadcrumbLinkClass()
    ├── breadcrumbSeparatorClass()
    ├── breadcrumbItemClass()
    │   └── breadcrumbLinkClass()
    ├── breadcrumbSeparatorClass()
    └── breadcrumbItemClass()
        └── breadcrumbPageClass()

Basic

A basic breadcrumb with a home link and a components link.

import { html } from '@webjsdev/core';
import {
  breadcrumbListClass, breadcrumbItemClass, breadcrumbLinkClass, breadcrumbPageClass, breadcrumbSeparatorClass,
} from '#components/ui/breadcrumb.ts';
import { ChevronRightIcon } from '#lib/ui/lucide.ts';

const separator = () => html`
  <li data-slot="breadcrumb-separator" role="presentation" aria-hidden="true" class=${breadcrumbSeparatorClass()}>${ChevronRightIcon('cn-rtl-flip')}</li>
`;

export default function BreadcrumbBasic() {
  return html`
    <nav aria-label="breadcrumb" data-slot="breadcrumb">
      <ol data-slot="breadcrumb-list" class=${breadcrumbListClass()}>
        <li data-slot="breadcrumb-item" class=${breadcrumbItemClass()}>
          <a data-slot="breadcrumb-link" href="#" class=${breadcrumbLinkClass()}>Home</a>
        </li>
        ${separator()}
        <li data-slot="breadcrumb-item" class=${breadcrumbItemClass()}>
          <a data-slot="breadcrumb-link" href="#" class=${breadcrumbLinkClass()}>Components</a>
        </li>
        ${separator()}
        <li data-slot="breadcrumb-item" class=${breadcrumbItemClass()}>
          <span data-slot="breadcrumb-page" role="link" aria-disabled="true" aria-current="page" class=${breadcrumbPageClass()}>Breadcrumb</span>
        </li>
      </ol>
    </nav>
  `;
}
View Code

Custom separator

The separator is whatever its <li> holds, so put any icon inside the item that carries breadcrumbSeparatorClass() to create a custom separator.

import { html } from '@webjsdev/core';
import {
  breadcrumbListClass, breadcrumbItemClass, breadcrumbLinkClass, breadcrumbPageClass, breadcrumbSeparatorClass,
} from '#components/ui/breadcrumb.ts';
import { DotIcon } from '#lib/ui/lucide.ts';

// A custom separator is whatever the separator item holds.
const separator = () => html`
  <li data-slot="breadcrumb-separator" role="presentation" aria-hidden="true" class=${breadcrumbSeparatorClass()}>${DotIcon()}</li>
`;

export default function BreadcrumbSeparatorDemo() {
  return html`
    <nav aria-label="breadcrumb" data-slot="breadcrumb">
      <ol data-slot="breadcrumb-list" class=${breadcrumbListClass()}>
        <li data-slot="breadcrumb-item" class=${breadcrumbItemClass()}>
          <a data-slot="breadcrumb-link" href="/" class=${breadcrumbLinkClass()}>Home</a>
        </li>
        ${separator()}
        <li data-slot="breadcrumb-item" class=${breadcrumbItemClass()}>
          <a data-slot="breadcrumb-link" href="/components" class=${breadcrumbLinkClass()}>Components</a>
        </li>
        ${separator()}
        <li data-slot="breadcrumb-item" class=${breadcrumbItemClass()}>
          <span data-slot="breadcrumb-page" role="link" aria-disabled="true" aria-current="page" class=${breadcrumbPageClass()}>Breadcrumb</span>
        </li>
      </ol>
    </nav>
  `;
}
View Code

You can put a <ui-dropdown-menu> inside a breadcrumb item to create a dropdown in the breadcrumb.

import { html } from '@webjsdev/core';
import {
  breadcrumbListClass, breadcrumbItemClass, breadcrumbLinkClass, breadcrumbPageClass, breadcrumbSeparatorClass,
} from '#components/ui/breadcrumb.ts';
import { ChevronDownIcon, DotIcon } from '#lib/ui/lucide.ts';

const separator = () => html`
  <li data-slot="breadcrumb-separator" role="presentation" aria-hidden="true" class=${breadcrumbSeparatorClass()}>${DotIcon()}</li>
`;

export default function BreadcrumbDropdown() {
  return html`
    <nav aria-label="breadcrumb" data-slot="breadcrumb">
      <ol data-slot="breadcrumb-list" class=${breadcrumbListClass()}>
        <li data-slot="breadcrumb-item" class=${breadcrumbItemClass()}>
          <a data-slot="breadcrumb-link" href="/" class=${breadcrumbLinkClass()}>Home</a>
        </li>
        ${separator()}
        <li data-slot="breadcrumb-item" class=${breadcrumbItemClass()}>
          <ui-dropdown-menu>
            <ui-dropdown-menu-trigger>
              <button type="button" class="flex items-center gap-1">
                Components
                ${ChevronDownIcon('size-3.5')}
              </button>
            </ui-dropdown-menu-trigger>
            <ui-dropdown-menu-content align="start">
              <ui-dropdown-menu-group>
                <ui-dropdown-menu-item>Documentation</ui-dropdown-menu-item>
                <ui-dropdown-menu-item>Themes</ui-dropdown-menu-item>
                <ui-dropdown-menu-item>GitHub</ui-dropdown-menu-item>
              </ui-dropdown-menu-group>
            </ui-dropdown-menu-content>
          </ui-dropdown-menu>
        </li>
        ${separator()}
        <li data-slot="breadcrumb-item" class=${breadcrumbItemClass()}>
          <span data-slot="breadcrumb-page" role="link" aria-disabled="true" aria-current="page" class=${breadcrumbPageClass()}>Breadcrumb</span>
        </li>
      </ol>
    </nav>
  `;
}
View Code

Collapsed

Use breadcrumbEllipsisClass() to show a collapsed state when the breadcrumb is too long.

import { html } from '@webjsdev/core';
import {
  breadcrumbListClass, breadcrumbItemClass, breadcrumbLinkClass, breadcrumbPageClass,
  breadcrumbSeparatorClass, breadcrumbEllipsisClass,
} from '#components/ui/breadcrumb.ts';
import { ChevronRightIcon, MoreHorizontalIcon } from '#lib/ui/lucide.ts';

const separator = () => html`
  <li data-slot="breadcrumb-separator" role="presentation" aria-hidden="true" class=${breadcrumbSeparatorClass()}>${ChevronRightIcon('cn-rtl-flip')}</li>
`;

export default function BreadcrumbEllipsisDemo() {
  return html`
    <nav aria-label="breadcrumb" data-slot="breadcrumb">
      <ol data-slot="breadcrumb-list" class=${breadcrumbListClass()}>
        <li data-slot="breadcrumb-item" class=${breadcrumbItemClass()}>
          <a data-slot="breadcrumb-link" href="/" class=${breadcrumbLinkClass()}>Home</a>
        </li>
        ${separator()}
        <li data-slot="breadcrumb-item" class=${breadcrumbItemClass()}>
          <span data-slot="breadcrumb-ellipsis" role="presentation" aria-hidden="true" class=${breadcrumbEllipsisClass()}>
            ${MoreHorizontalIcon()}
            <span class="sr-only">More</span>
          </span>
        </li>
        ${separator()}
        <li data-slot="breadcrumb-item" class=${breadcrumbItemClass()}>
          <a data-slot="breadcrumb-link" href="/docs/components" class=${breadcrumbLinkClass()}>Components</a>
        </li>
        ${separator()}
        <li data-slot="breadcrumb-item" class=${breadcrumbItemClass()}>
          <span data-slot="breadcrumb-page" role="link" aria-disabled="true" aria-current="page" class=${breadcrumbPageClass()}>Breadcrumb</span>
        </li>
      </ol>
    </nav>
  `;
}
View Code

A breadcrumb link is a plain <a> with breadcrumbLinkClass(). WebJs's client router handles a plain link on its own.

import { html } from '@webjsdev/core';
import {
  breadcrumbListClass, breadcrumbItemClass, breadcrumbLinkClass, breadcrumbPageClass, breadcrumbSeparatorClass,
} from '#components/ui/breadcrumb.ts';
import { ChevronRightIcon } from '#lib/ui/lucide.ts';

const separator = () => html`
  <li data-slot="breadcrumb-separator" role="presentation" aria-hidden="true" class=${breadcrumbSeparatorClass()}>${ChevronRightIcon('cn-rtl-flip')}</li>
`;

// A plain <a> is the router link: WebJs's client router picks it up on its own.
export default function BreadcrumbLinkDemo() {
  return html`
    <nav aria-label="breadcrumb" data-slot="breadcrumb">
      <ol data-slot="breadcrumb-list" class=${breadcrumbListClass()}>
        <li data-slot="breadcrumb-item" class=${breadcrumbItemClass()}>
          <a data-slot="breadcrumb-link" href="/" class=${breadcrumbLinkClass()}>Home</a>
        </li>
        ${separator()}
        <li data-slot="breadcrumb-item" class=${breadcrumbItemClass()}>
          <a data-slot="breadcrumb-link" href="/components" class=${breadcrumbLinkClass()}>Components</a>
        </li>
        ${separator()}
        <li data-slot="breadcrumb-item" class=${breadcrumbItemClass()}>
          <span data-slot="breadcrumb-page" role="link" aria-disabled="true" aria-current="page" class=${breadcrumbPageClass()}>Breadcrumb</span>
        </li>
      </ol>
    </nav>
  `;
}
View Code

RTL

To enable RTL support, see the RTL configuration guide.

import { html } from '@webjsdev/core';
import {
  breadcrumbListClass, breadcrumbItemClass, breadcrumbLinkClass, breadcrumbPageClass, breadcrumbSeparatorClass,
} from '#components/ui/breadcrumb.ts';
import { ChevronDownIcon, DotIcon } from '#lib/ui/lucide.ts';

const translations = {
  en: {
    dir: 'ltr',
    values: {
      home: 'Home',
      components: 'Components',
      documentation: 'Documentation',
      themes: 'Themes',
      github: 'GitHub',
      breadcrumb: 'Breadcrumb',
    },
  },
  ar: {
    dir: 'rtl',
    values: {
      home: 'الرئيسية',
      components: 'المكونات',
      documentation: 'التوثيق',
      themes: 'السمات',
      github: 'جيت هاب',
      breadcrumb: 'مسار التنقل',
    },
  },
  he: {
    dir: 'rtl',
    values: {
      home: 'בית',
      components: 'רכיבים',
      documentation: 'תיעוד',
      themes: 'ערכות נושא',
      github: 'גיטהאב',
      breadcrumb: 'פירורי לחם',
    },
  },
};

const separator = () => html`
  <li data-slot="breadcrumb-separator" role="presentation" aria-hidden="true" class=${breadcrumbSeparatorClass()}>${DotIcon()}</li>
`;

export default function BreadcrumbRtl() {
  const lang = 'ar';
  const { dir, values: t } = translations[lang];

  return html`
    <nav aria-label="breadcrumb" data-slot="breadcrumb" dir=${dir} lang=${lang}>
      <ol data-slot="breadcrumb-list" class=${breadcrumbListClass()}>
        <li data-slot="breadcrumb-item" class=${breadcrumbItemClass()}>
          <a data-slot="breadcrumb-link" href="/" class=${breadcrumbLinkClass()}>${t.home}</a>
        </li>
        ${separator()}
        <li data-slot="breadcrumb-item" class=${breadcrumbItemClass()}>
          <ui-dropdown-menu>
            <ui-dropdown-menu-trigger>
              <button type="button" class="flex items-center gap-1">
                ${t.components}
                ${ChevronDownIcon('size-3.5')}
              </button>
            </ui-dropdown-menu-trigger>
            <ui-dropdown-menu-content data-lang=${lang}>
              <ui-dropdown-menu-group>
                <ui-dropdown-menu-item>${t.documentation}</ui-dropdown-menu-item>
                <ui-dropdown-menu-item>${t.themes}</ui-dropdown-menu-item>
                <ui-dropdown-menu-item>${t.github}</ui-dropdown-menu-item>
              </ui-dropdown-menu-group>
            </ui-dropdown-menu-content>
          </ui-dropdown-menu>
        </li>
        ${separator()}
        <li data-slot="breadcrumb-item" class=${breadcrumbItemClass()}>
          <span data-slot="breadcrumb-page" role="link" aria-disabled="true" aria-current="page" class=${breadcrumbPageClass()}>${t.breadcrumb}</span>
        </li>
      </ol>
    </nav>
  `;
}
View Code

API Reference

Every part is a class helper with no options. Put it on the native element below, together with the data-slot and the ARIA attributes the helper does not emit.

The root navigation element that wraps the breadcrumb. It needs no classes.

HelperElementAttributes
none<nav>aria-label="breadcrumb", data-slot="breadcrumb"

The ordered list of breadcrumb items.

HelperElementAttributes
breadcrumbListClass()<ol>data-slot="breadcrumb-list"

Wraps an individual breadcrumb item.

HelperElementAttributes
breadcrumbItemClass()<li>data-slot="breadcrumb-item"

A clickable link in the breadcrumb.

HelperElementAttributes
breadcrumbLinkClass()<a>data-slot="breadcrumb-link", href

The current page in the breadcrumb (not clickable).

HelperElementAttributes
breadcrumbPageClass()<span>data-slot="breadcrumb-page", aria-current="page"

A separator between breadcrumb items. Its content is the separator icon, so put any icon inside it.

HelperElementAttributes
breadcrumbSeparatorClass()<li>data-slot="breadcrumb-separator", role="presentation", aria-hidden="true"

An ellipsis indicator for collapsed breadcrumb items. Put an icon and an sr-only label inside it.

HelperElementAttributes
breadcrumbEllipsisClass()<span>data-slot="breadcrumb-ellipsis", role="presentation", aria-hidden="true"