sp-breadcrumbs

compact

true

false

label

max-visible-items

NPM 1.7.0

View Storybook

Overview

API

Changelog

Overview

An <sp-breadcrumbs> shows hierarchy and navigational context for a user's location within an app. The <sp-breadcrumbs> component defines its list of items using child <sp-breadcrumb-item> elements placed in its default slot.

View the design documentation for this component.

Usage

yarn add @spectrum-web-components/breadcrumbs

Import the side effectful registration of <sp-breadcrumbs> and <sp-breadcrumb-item> via:

import '@spectrum-web-components/breadcrumbs/sp-breadcrumbs.js';
import '@spectrum-web-components/breadcrumbs/sp-breadcrumb-item.js';

When looking to leverage the Breadcrumbs or BreadcrumbItem base class as a type and/or for extension purposes, do so via:

import {
    Breadcrumbs,
    BreadcrumbItem,
} from '@spectrum-web-components/breadcrumbs';

Anatomy

Breadcrumbs consist of several key parts:

A breadcrumbs list, usually consisting of multiple breadcrumb items, with a separator between each item.
A breadcrumbs title at the end of the list displaying the current location within the hierarchy.
A truncation menu may also appear, which displays all options within a breadcrumb. Within the menu, items are listed with the hierarchy ordered from the top (root) to the bottom, and will include the currently selected item. Breadcrumbs truncate when there isn't enough space to show all items, or when the list contains five or more levels. Truncation helps manage space and keep the most relevant breadcrumbs visible in deeply nested hierarchies.

<sp-breadcrumbs>
    <sp-breadcrumb-item value="home">Home</sp-breadcrumb-item>
    <sp-breadcrumb-item value="trend">Trend</sp-breadcrumb-item>
    <sp-breadcrumb-item value="assets">March 2019 Assets</sp-breadcrumb-item>
</sp-breadcrumbs>

Options

Compact

When needing to optimize for functional space of <sp-breadcrumbs>, the compact property can be used to reduce the height of the breadcrumbs while still maintaining the proper user context.

<sp-breadcrumbs compact>
    <sp-breadcrumb-item value="1">Home</sp-breadcrumb-item>
    <sp-breadcrumb-item value="2">Trend</sp-breadcrumb-item>
    <sp-breadcrumb-item value="3">March 2019 Assets</sp-breadcrumb-item>
</sp-breadcrumbs>

Overflowing

When space becomes limited or the maximum visible items are reached, the component automatically moves the first breadcrumbs into an action menu, adjusting dynamically as the window is resized.

By default, the maximum number of visible breadcrumbs is 4, as recommended by Spectrum Design. You can override this by using the max-visible-items attribute. The <sp-breadcrumbs> component will always display the action menu and the breadcrumbs title, so the minimum number of visible items is 1.

Default

<sp-breadcrumbs>
    <sp-breadcrumb-item value="your_stuff">Your stuff</sp-breadcrumb-item>
    <sp-breadcrumb-item value="team">Team</sp-breadcrumb-item>
    <sp-breadcrumb-item value="in_progress">In progress</sp-breadcrumb-item>
    <sp-breadcrumb-item value="files">Files</sp-breadcrumb-item>
    <sp-breadcrumb-item value="trend">Trend</sp-breadcrumb-item>
    <sp-breadcrumb-item value="winter">Winter</sp-breadcrumb-item>
    <sp-breadcrumb-item value="assets">Assets</sp-breadcrumb-item>
    <sp-breadcrumb-item value="18x24">18x24</sp-breadcrumb-item>
</sp-breadcrumbs>

One maximum visible item

<sp-breadcrumbs max-visible-items="1">
    <sp-breadcrumb-item value="your_stuff">Your stuff</sp-breadcrumb-item>
    <sp-breadcrumb-item value="team">Team</sp-breadcrumb-item>
    <sp-breadcrumb-item value="in_progress">In progress</sp-breadcrumb-item>
    <sp-breadcrumb-item value="files">Files</sp-breadcrumb-item>
    <sp-breadcrumb-item value="trend">Trend</sp-breadcrumb-item>
    <sp-breadcrumb-item value="winter">Winter</sp-breadcrumb-item>
    <sp-breadcrumb-item value="assets">Assets</sp-breadcrumb-item>
    <sp-breadcrumb-item value="18x24">18x24</sp-breadcrumb-item>
</sp-breadcrumbs>

Three maximum visible items

<sp-breadcrumbs max-visible-items="3">
    <sp-breadcrumb-item value="your_stuff">Your stuff</sp-breadcrumb-item>
    <sp-breadcrumb-item value="team">Team</sp-breadcrumb-item>
    <sp-breadcrumb-item value="in_progress">In progress</sp-breadcrumb-item>
    <sp-breadcrumb-item value="files">Files</sp-breadcrumb-item>
    <sp-breadcrumb-item value="trend">Trend</sp-breadcrumb-item>
    <sp-breadcrumb-item value="winter">Winter</sp-breadcrumb-item>
    <sp-breadcrumb-item value="assets">Assets</sp-breadcrumb-item>
    <sp-breadcrumb-item value="18x24">18x24</sp-breadcrumb-item>
</sp-breadcrumbs>

Resizable

These breadcrumbs are in a resizable container. Reduce the size of the container to see how the maximum number of visible items changes.

<div style="border: 2px solid; padding: 20px; resize: both; overflow: auto;">
    <sp-breadcrumbs max-visible-items="8">
        <sp-breadcrumb-item value="your_stuff">Your stuff</sp-breadcrumb-item>
        <sp-breadcrumb-item value="team">Team</sp-breadcrumb-item>
        <sp-breadcrumb-item value="in_progress">In progress</sp-breadcrumb-item>
        <sp-breadcrumb-item value="files">Files</sp-breadcrumb-item>
        <sp-breadcrumb-item value="trend">Trend</sp-breadcrumb-item>
        <sp-breadcrumb-item value="winter">Winter</sp-breadcrumb-item>
        <sp-breadcrumb-item value="assets">Assets</sp-breadcrumb-item>
        <sp-breadcrumb-item value="18x24">18x24</sp-breadcrumb-item>
    </sp-breadcrumbs>
</div>

Show root

Use the root slot on the first breadcrumb item to always render the first breadcrumb item, even if the breadcrumbs are overflowing. The root will always show in addition to the number of items specified with max-visible-items.

Overflowing

<sp-breadcrumbs>
    <sp-breadcrumb-item slot="root" value="your_stuff">
        Your stuff
    </sp-breadcrumb-item>
    <sp-breadcrumb-item value="team">Files</sp-breadcrumb-item>
    <sp-breadcrumb-item value="trend">Trend</sp-breadcrumb-item>
    <sp-breadcrumb-item value="winter">Winter</sp-breadcrumb-item>
    <sp-breadcrumb-item value="assets">Assets</sp-breadcrumb-item>
    <sp-breadcrumb-item value="18x24">18x24</sp-breadcrumb-item>
</sp-breadcrumbs>

Not overflowing

<sp-breadcrumbs>
    <sp-breadcrumb-item slot="root" value="your_stuff">
        Your stuff
    </sp-breadcrumb-item>
    <sp-breadcrumb-item value="files">Files</sp-breadcrumb-item>
    <sp-breadcrumb-item value="trend">Trend</sp-breadcrumb-item>
    <sp-breadcrumb-item value="winter">Winter</sp-breadcrumb-item>
    <sp-breadcrumb-item value="assets">Assets</sp-breadcrumb-item>
</sp-breadcrumbs>

Links

By default, sp-breadcrumbs emits a change event when clicking on one of its children. However, there may be cases in which clicking should redirect to another page. This can be achieved by using the href attribute instead of value. Please note that the change event will no longer be triggered in this case.

<sp-breadcrumbs>
    <sp-breadcrumb-item href="https://opensource.adobe.com/">
        Home
    </sp-breadcrumb-item>
    <sp-breadcrumb-item href="https://opensource.adobe.com/trend">
        Trend
    </sp-breadcrumb-item>
    <sp-breadcrumb-item href="https://opensource.adobe.com/assets">
        March 2019 Assets
    </sp-breadcrumb-item>
</sp-breadcrumbs>

Custom Action Menu

The component offers the possibility to replace the action menu's icon with a custom one using the icon slot. Moreover, for accessibility purposes you can provide an internationalized string for the menu label using the menu-label attribute.

<sp-breadcrumbs menu-label="Settings">
    <sp-icon-settings slot="icon"></sp-icon-settings>

    <sp-breadcrumb-item value="displays">Displays</sp-breadcrumb-item>
    <sp-breadcrumb-item value="main">Main display</sp-breadcrumb-item>
    <sp-breadcrumb-item value="brightness">Brightness</sp-breadcrumb-item>
    <sp-breadcrumb-item value="presets">Presets</sp-breadcrumb-item>
    <sp-breadcrumb-item value="1">Preset #1</sp-breadcrumb-item>
</sp-breadcrumbs>

Accessibility

The <sp-breadcrumbs> component provides the following accessibility features:

Automatically sets role="navigation" to ensure proper semantic meaning for assistive technologies
Uses semantic markup by rendering a <ul> with each <sp-breadcrumb-item> assigned role="listitem"
The last breadcrumb item automatically receives aria-current="page" to indicate the current location
Sets aria-label based on the label property, defaulting to "Breadcrumbs" if none is provided
Each breadcrumb item is keyboard accessible with tabindex="0"
Provides an accessible action menu with keyboard navigation and screen reader support

Best practices

Limit breadcrumb depth: Keep breadcrumbs to 4-5 levels maximum to avoid overwhelming users
Use descriptive labels: Each breadcrumb item should clearly identify the section or page
Maintain consistent hierarchy: Always start from the root and progress logically to the current page
Handle overflow gracefully: Use the max-visible-items property to control truncation behavior
Provide meaningful menu labels: Use the menu-label attribute to describe the overflow menu purpose

Attributes and Properties

Property

Attribute

Type

Default

Description

compact

boolean

false

compact option is useful for reducing the height of the breadcrumbs

label

string

''

Accessible name for the Breadcrumbs component

maxVisibleItems

max-visible-items

number

4

Override the maximum number of visible items

menuLabel

menu-label

string

'More items'

Change the default label of the action menu

Slots

Name

Description

icon

change the default icon of the action menu

root

Breadcrumb item to always display

default slot

Breadcrumb items

Events

Name

Type

Description

change

Event

Announces the selected breadcrumb item

Patch Changes

Updated dependencies [3aeafdd]:
- @spectrum-web-components/menu@1.7.0
- @spectrum-web-components/action-menu@1.7.0
- @spectrum-web-components/icons-workflow@1.7.0
- @spectrum-web-components/link@1.7.0
- @spectrum-web-components/base@1.7.0

1.6.0

Patch Changes

Updated dependencies [f6cebbd, a9727d2]:
- @spectrum-web-components/icons-workflow@1.6.0
- @spectrum-web-components/menu@1.6.0
- @spectrum-web-components/action-menu@1.6.0
- @spectrum-web-components/link@1.6.0
- @spectrum-web-components/base@1.6.0

1.5.0

Patch Changes

#5277 daeb11f Thanks @renovate! - /Users/cas/Projects/work/spectrum-web-components/yarn.lock
Updated dependencies [86bcd12, 165a904, 4c2f908, a69accb]:
- @spectrum-web-components/menu@1.5.0
- @spectrum-web-components/link@1.5.0
- @spectrum-web-components/action-menu@1.5.0
- @spectrum-web-components/icons-workflow@1.5.0
- @spectrum-web-components/base@1.5.0

1.4.0

Patch Changes

Updated dependencies [2a0422e, 6618422, 82212f4]:
- @spectrum-web-components/menu@1.4.0
- @spectrum-web-components/action-menu@1.4.0
- @spectrum-web-components/icons-workflow@1.4.0
- @spectrum-web-components/link@1.4.0
- @spectrum-web-components/base@1.4.0

1.3.0

Patch Changes

Updated dependencies [ea38ef0, 468314f]:
- @spectrum-web-components/action-menu@1.3.0
- @spectrum-web-components/menu@1.3.0
- @spectrum-web-components/icons-workflow@1.3.0
- @spectrum-web-components/link@1.3.0
- @spectrum-web-components/base@1.3.0

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.