Breadcrumbs

Usage

Breadcrumbs is a navigational component used to display a hierarchical path of the user’s current location within an interface. They help users understand their position in relation to the broader structure of a product’s information architecture and allow users to move up or down levels within the site or application.

Breadcrumbs are typically placed at the top of a page or content area, ensuring users can easily locate and traverse to previously visited pages or higher-level sections. They are especially useful in complex interfaces or multi-level navigational structures.

Types

There is a single type of Breadcrumbs component.

Anatomy and Behavior

Anatomy

A Breadcrumbs component consists of multiple elements that together provide clear navigation cues:

1. Breadcrumb Items (Links) – Each breadcrumb item is a nested individual Link Secondary component representing a navigable section of the site or product. By default, they display the name of the corresponding page or section. Clicking on a breadcrumb item takes the user to that location.
2. Icon (optional) - Comes from the Link Secondary component. In Breadcrumbs, we only use the Leading position for the icon.
3. Separators – Visual elements (slashes) placed between Breadcrumb items. They help the user distinguish individual items at a glance. They are not clickable.
4. Ellipsis (Truncation Marker) – A clickable element represented by three dots (...) that appears when there is not enough space to display all breadcrumb items. Clicking on the ellipsis expands the truncated sections of the breadcrumb, making them visible while potentially hiding other sections.

Behavior

• Normal Display: When there is sufficient space, all breadcrumb items and separators are fully visible in a linear sequence.
• Truncation on Overflow: When horizontal space is limited, the middle portions of the breadcrumb path are truncated and replaced with an ellipsis (...). The ellipsis indicates that additional path items exist but are currently hidden.
• Expandable Ellipsis: Clicking on the ellipsis expands the truncated middle section to display the hidden breadcrumb items. Upon expansion, space constraints may cause either the beginning or end of the breadcrumb path to truncate instead, ensuring the currently expanded middle section stays visible. This dynamic truncation ensures at least the current page (last breadcrumb item) is always visible, along with the root and/or other key anchors depending on the available space.

The dynamic truncation in Breadcrumbs ensures an optimal balance between readability and available space. Designers and developers should test various viewport sizes and content lengths to confirm truncation behavior aligns with user needs.

States

All state variations in the Breadcrumbs component are inherited from the underlying Link component used for each breadcrumb item.

Gaps and Sizes

• Breadcrumb Item spacing: S
• Breadcrumb Item and separator gap: S

Tokens

SCSS Variable

Value

$breadcrumb-color

--color-grey-54

Configurations

• Level 1
  /
• Level 2
  /
• Level 3
  /
• /
• Level 5
• ...
• /
  Level 10

click on breadcrumb:

Developer Notes

• The breadcrumb navigation structure is provided via the crumbs prop, which is an array of objects containing name and path properties.
• The modelValue prop contains the path of the currently selected breadcrumb.
• Clicking a breadcrumb emits the update:modelValue event, updating the parent component with the selected path.
• The component supports two-way binding using v-model.
• To truncate the elements applyTruncation should be true and maxVisibleCrumbs(number) must be set to the value of elemets to be seen

<script lang="ts" setup>
import { Breadcrumbs } from '@/components';

const breadcrumbsExample = [
  { name: 'Home', path: '/', icon: 'undo'},
  { name: 'Projects', path: '/projects' },
  { name: 'Details', path: '/projects/details' },
];

const selectedPath = ref('/');

function manageSelectedPath(value) {
  console.log("Selected Path", value);
}

</script>

<template>
  <Breadcrumbs 
    v-model="selectedPath" 
    :crumbs="breadcrumbsExample" 
    @update:modelValue="manageSelectedPath"
    maxVisibleCrumbs=6
    :applyTruncation="true"
  />
</template>