<c-breadcrumb>
A navigation aid naming where the current page sits in a site's hierarchy: one line of crumbs from the top of the hierarchy down to the current page, the middle ones folding behind a "…" button when the line runs out of room.
Usage
Crumbs
Each c-breadcrumb-item is a crumb, written in order from the top of the
hierarchy down. A crumb with an href is a link; the last crumb is always the
current page — shown as plain text and announced as the current page, with no
attribute to set — and a crumb without an href names a level that has no page
of its own. An icon goes in a crumb's icon slot, sized 20px in the row and
18px in the fold panel unless the c-icon sets its own size; give an
icon-only crumb an aria-label, which names its link:
<c-breadcrumb>
<c-breadcrumb-item aria-label="Home" href="/">
<c-icon slot="icon" :path="mdiHome" />
</c-breadcrumb-item>
<c-breadcrumb-item href="/projects">Projects</c-breadcrumb-item>
<c-breadcrumb-item>Project #1</c-breadcrumb-item>
</c-breadcrumb>
The chevron between crumbs is drawn by the breadcrumb and is not configurable.
Folding
The breadcrumb is always one line, as wide as the space it is given. When its crumbs do not fit, the middle ones fold behind a "…" button, the crumb nearest the first one first; the first crumb and the current crumb never fold. The button opens a panel listing the folded crumbs as links: Tab or the up and down arrow keys move through them, Home and End jump to the first and the last, and Escape or a press outside closes it. The down or up arrow on the button opens the panel straight onto its first or last crumb. Once nothing more can fold, the current crumb's label shortens with an ellipsis, then the first crumb's; a shortened crumb shows its full label as a tooltip.
The breadcrumb assigns its crumbs to slots to fold them — never set slot on a
crumb yourself. In a flex row, let the breadcrumb take the remaining space so
it can unfold again when the row grows:
c-breadcrumb::part(root) {
flex: 1;
min-width: 0;
}
Single-page apps
A crumb is a real link, so it opens in a new tab and can be copied. To route
inside a single-page app, keep the href and intercept the crumb's click — it
also fires for Enter, and for a crumb in the fold panel:
<c-breadcrumb-item
href="/projects"
@click.exact.prevent="router.push('/projects')"
>
Projects
</c-breadcrumb-item>
The .exact modifier leaves Ctrl-, Cmd- and Shift-clicks to the browser.
Texts
The navigation's accessible name and the "…" button's label can be replaced
for another language through the texts object, merged over the English
defaults. The button's label is a function of the number of folded crumbs, so
the object must be bound as a DOM property:
<c-breadcrumb
:texts="{
breadcrumb: 'Murupolku',
fold: (count) => `Näytä ${count} lisää`,
}"
/>
To translate every breadcrumb at once, set texts app-wide with
applyDefaults({ 'c-breadcrumb': { texts } }) (Customization → App-wide prop
defaults); a per-instance texts still wins key by key.
Customization
Crumbs expose the current and folded custom states, so a crumb can be
restyled per state:
c-breadcrumb-item:state(current)::part(content) {
font-weight: 400;
}
The fold panel hides its scrollbar and ends on a half-visible crumb when it overflows. To bring the native scrollbar back:
c-breadcrumb::part(panel-list) {
scrollbar-width: auto;
}
Examples
<template>
<c-breadcrumb>
<c-breadcrumb-item aria-label="Home" href="https://csc.fi">
<c-icon slot="icon" :path="mdiHome" />
</c-breadcrumb-item>
<c-breadcrumb-item href="https://csc.fi/en/services">
Services
</c-breadcrumb-item>
<c-breadcrumb-item>Supercomputers</c-breadcrumb-item>
</c-breadcrumb>
</template>
<script setup lang="ts">
import { mdiHome } from '@mdi/js';
</script>
<template>
<!-- Drag the corner to narrow the box: the middle crumbs fold behind "…",
then the current crumb's label shortens. -->
<div
style="
resize: horizontal;
overflow: hidden;
width: 420px;
min-width: 160px;
max-width: 100%;
padding: 8px;
border: 1px dashed currentColor;
"
>
<c-breadcrumb>
<c-breadcrumb-item aria-label="Home" href="https://csc.fi">
<c-icon slot="icon" :path="mdiHome" />
</c-breadcrumb-item>
<c-breadcrumb-item href="https://csc.fi/en/services">
Services
</c-breadcrumb-item>
<c-breadcrumb-item href="https://csc.fi/en/services/computing">
Computing
</c-breadcrumb-item>
<c-breadcrumb-item href="https://csc.fi/en/services/computing/lumi">
LUMI supercomputer
</c-breadcrumb-item>
<c-breadcrumb-item>Applying for computing resources</c-breadcrumb-item>
</c-breadcrumb>
</div>
</template>
<script setup lang="ts">
import { mdiHome } from '@mdi/js';
</script>
<template>
<div>
<c-breadcrumb>
<c-breadcrumb-item
v-for="page in crumbs"
:key="page.path"
:href="page.path"
@click.exact.prevent="navigate(page.path)"
>
{{ page.name }}
</c-breadcrumb-item>
</c-breadcrumb>
<p>Route: {{ route }}</p>
</div>
</template>
<script setup lang="ts">
import { computed, ref } from 'vue';
const PAGES = [
{ name: 'Home', path: '/' },
{ name: 'Projects', path: '/projects' },
{ name: 'Project #1', path: '/projects/1' },
{ name: 'Members', path: '/projects/1/members' },
];
// Stands in for the router's current route.
const route = ref('/projects/1/members');
const crumbs = computed(() =>
PAGES.slice(0, PAGES.findIndex((page) => page.path === route.value) + 1),
);
const navigate = (path: string) => {
// In an app: router.push(path)
route.value = path;
};
</script>
<template>
<div style="width: 320px; max-width: 100%">
<c-breadcrumb :texts>
<c-breadcrumb-item href="https://csc.fi">Etusivu</c-breadcrumb-item>
<c-breadcrumb-item href="https://csc.fi/palvelut">
Palvelut
</c-breadcrumb-item>
<c-breadcrumb-item href="https://csc.fi/palvelut/laskenta">
Laskenta
</c-breadcrumb-item>
<c-breadcrumb-item>Supertietokoneet</c-breadcrumb-item>
</c-breadcrumb>
</div>
</template>
<script setup lang="ts">
import type { CBreadcrumbTexts } from '@cscfi/csc-ui';
const texts: CBreadcrumbTexts = {
breadcrumb: 'Murupolku',
fold: (count) => `Näytä ${count} lisää`,
};
</script>
API reference
<c-breadcrumb>
A navigation aid naming where the current page sits in a site's hierarchy: one line of crumbs from the top of the hierarchy down to the current page, the middle ones folding behind a "…" button when the line runs out of room.
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
texts | — | | {} app default | UI text overrides (i18n), merged over the English defaults. Objects have no attribute form — set it as a property |
app default marks a prop you can set for every instance at once with applyDefaults() — an explicit attribute or property on an instance still wins.
Slots
| Slot | Description |
|---|---|
default | The crumbs (`c-breadcrumb-item`), from the top of the hierarchy down to the current page |
CSS parts
Style from outside with c-breadcrumb::part(name) — parts are the library's only styling customization API.
| Part | Description |
|---|---|
root | The `<nav>` landmark; it takes the full width it is given and folds the crumbs to fit it |
list | The one-line list of crumbs |
separator | The chevron before the fold button |
fold-button | The "…" button standing in for the folded crumbs |
panel | The top-layer popover holding the fold panel, anchored below the fold button |
panel-list | The fold panel's list surface holding the folded crumbs |
Types
Importable from the package root: import type { … } from '@cscfi/csc-ui'
CBreadcrumbTexts
UI texts of `c-breadcrumb`, shallow-merged over the English defaults. Static labels are strings; interpolated ones are functions.
export interface CBreadcrumbTexts {
/** Accessible name of the breadcrumb navigation. */
breadcrumb?: string;
/** Accessible name of the fold button; receives the number of folded crumbs. */
fold?: (count: number) => string;
}<c-breadcrumb-item>
One crumb in a `c-breadcrumb`: a link to a level of the hierarchy, or, as the last crumb, the current page.
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
href | href | string | '' | URL of the page the crumb leads to. Ignored on the current crumb (the last one); a crumb without it names a level that has no page and renders as plain text |
target | target | string | '' | Browsing context the link opens in; the same tab when unset |
Slots
| Slot | Description |
|---|---|
default | The crumb's label |
icon | An icon shown before the label (e.g. a `c-icon`); give an icon-only crumb an `aria-label` |
CSS parts
Style from outside with c-breadcrumb-item::part(name) — parts are the library's only styling customization API.
| Part | Description |
|---|---|
root | The box holding the separator and the crumb (the crumb element is the list item); in the fold panel, the row |
separator | The chevron before every crumb but the first, hidden in the fold panel |
content | The link (or, without `href` and on the current crumb, the text) holding the icon and label |
label | The label text, truncated with an ellipsis when the breadcrumb runs out of room |
Custom states
Select on the host's live state with c-breadcrumb-item:state(name) — combine with ::part() for per-state styling, e.g. c-breadcrumb-item:state(checked)::part(indicator) targets the indicator only while checked.
| State | Description |
|---|---|
current | Present on the current crumb (the last one) |
folded | Present while the crumb is folded into the breadcrumb's fold panel |