Skip to content
bitboss-ui3.0.0-beta.64

BbBreadcrumbs

The trail that says where the reader is and how to get back up.

import { BbBreadcrumbs } from 'bitboss-ui';

On this page

Use it for

Put BbBreadcrumbs at the top of a detail view, above the title. It answers two questions at once: where am I, and how do I get back up.

Use something else when

  • BbTabs, if they are peer views of the same record: Overview, Activity, Settings
  • BbPagination, if the reader is stepping through a paged result set

Also see: Options and items.

Show one trail per view.

Passthrough

Hover or tap a part to outline it. The toggles turn on loading, errors and warnings where the component has them; only parts get a row.

The trail

Each item is { label } plus a navigation target. Add a unique value only to a crumb that needs a slot of its own.

A last item without a target is the current page: it renders as plain text with aria-current="page", out of the tab order. Give it an href and it is an ordinary link again, for a trail that stops at the parent page with the page title below it.

Coming from v2key → value, text → label

A crumb's key is now value and its text is now label; the crumb slots' scope says label too. npx bitboss-ui check --fix renames both fields on items it can see. The value must be a string: a numeric key that ran in v2 now fails type checking, and the fix is String(id).

Give every crumb its own target: href, to, or an onClick.

  • AppShell.vue

When the hierarchy lives in client state rather than in routes, give the ancestors an onClick. The crumbs are still real buttons, and crumbs folded into the overflow menu keep their handler. Never wrap the trail in your own click-to-route handler.

disabled works at two levels. On one item, that crumb loses its href and gains aria-disabled. On the component, every crumb and the overflow button freeze together. Use it for a level the reader can no longer open, rather than shipping a dead link.

Long trails fold themselves

You do not manage overflow.

Drag the corner to narrow the frame.

The earliest crumbs fold into the … menu, root first, and keep their targets there. The current page never folds: at the narrowest its label truncates, with the full text in a tooltip and for screen readers. If that is too little, give the trail a full-width row of its own.

Pass the full items array. Pre-slicing removes the keyboard-ready overflow menu.

The fold point is estimated from label text. Start with offset-width for icons, slots, and edge regions. Use estimation-bias, divider-width, gap-width, or ellipsis-width only when their matching visual changes. In a flex row, give the trail class="min-w-0 flex-auto" and keep its siblings shrink-0. The full trail renders on the server, then folds after hydration.

Icons and edge regions

A fixed icon per crumb is an item field, not a slot: prepend:icon and append:icon.

prepend and append hold content before and after the whole trail, outside the links: an environment badge, a compact action. Declare their width with offset-width, or the trail folds too late.

For content that varies per crumb, use item:prepend or item:append. These slots are inside the crumb link, so do not add interactive descendants. They replace that side's prepend:icon or append:icon. Their item.value can be undefined, since values are optional.

One crumb, its own slot

Every item with a value also gets slots named after it: #<value> replaces that crumb's label, #<value>:prepend and #<value>:append what sits before and after it.

Use these slots when one level needs richer content. A crumb in the overflow menu is a dropdown row with the same value and label, so it follows the dropdown's rules.

The slot name is the value in kebab-case: Order History, orderHistory and order_history are all served by #order-history. For a value with accents or another script, write #[slotKey(value)] with slotKey from bitboss-ui. A crumb without a value has no slot of its own; the name is never taken from its label.

Coming from v2slot names are kebab-case

Rename each per-crumb slot to the kebab-case value: a name in the old spelling matches no crumb, which then shows its default label. npx bitboss-ui check names the new spelling when the items are in the same file.

A value spelled like one of the component's own slots (prepend, append, divider, ellipsis, item) is an error.

Divider and overflow button

The separator between crumbs is a slot, and only a slot.

Dividers are decorative and stay aria-hidden, so never encode meaning in one. If yours is wider or narrower than the default, declare its width with divider-width.

The ellipsis slot receives overflowCount and keeps the accessible button and menu behaviour. Declare a replacement's width with ellipsis-width, as the demo does.

Coming from v2divider removed

There is no divider prop in v3, and passing it leaks an attribute onto the markup. The default separator is a small chevron, not a /. The default of divider-width moved from 5 to 16, which matters only if you had tuned the old value.