@spectrum-web-components/breadcrumbs

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

Changelog

1.8.0 (2025-09-23)

Minor Changes

sp-picker: Fixed escape key behavior in modal overlays containing picker components. Previously, pressing the Escape key when a picker was open inside a modal overlay would not properly close the modal, instead moving focus to the picker. Now, the escape key correctly closes the picker first (if open), then closes the modal overlay on subsequent escape key presses.

This fix adds a check for this.open in the picker's handleEscape method to ensure proper modal overlay closure behavior.

sp-overlay: Added allow-outside-click property to <sp-overlay> with deprecation notice. This property allows clicks outside the overlay to close it, but is not recommended for accessibility reasons and will be removed in a future version.

This property is being added as deprecated to support the fallback for showModal() which was removed as part of performance optimization. We will no longer support outside clicks for modal overlays as they violate accessibility guidelines.

The property defaults to false and shows deprecation warnings when used. Consider using explicit close buttons or modal/page overlay types instead for better accessibility.

sp-menu: Fixed : Fix iPad scrolling issue in picker dropdown where scrolling through menu items would accidentally select the first touched item and close the picker.

The fix implements touch gesture detection to distinguish between scrolling and selection. Added isScrolling getter for public API access. Test on iPad devices with long menus to validate scrolling behavior and selection accuracy.

sp-overlay: Fixed : Added body scroll prevention for modal and page overlays. Overlay automatically blocks body scroll when modal or page overlays are open and restores the original scroll state when they are closed, improving user experience and accessibility for modal dialogs.

sp-clear-button: Clear button styles have been updated to the latest Spectrum CSS version of the clear button. This update includes a major reduction in the number of custom property abstractions needed to support the multiple theming layers (as seen in the styles package).

This update spans the following additional packages:

• @spectrum-web-components/button
• @spectrum-web-components/styles

As the updated styles now offer additional styling options, we have added the following API to the clear button component that exists in the button package:

• quiet - when set to true, the button will be rendered as a quiet button. This is useful for cases where you want to use the clear button in a more subtle way.
• disabled - when set to true, the button will be rendered as a disabled button.
• static-color - currently this only supports the white context color. This is useful for cases where the button appears on a dark background texture. This is a replacement for the previously used variant="overBackground" attribute which is deprecated.

Deprecation

The variant="overBackground" attribute is deprecated; please use the new static-color="white" attribute instead. When this property is used in the component, a deprecation warning will be shown in the console when in debug mode. The variant attribute will be removed in a future release.

sp-card: Fixed the card component's CSS by moving block-size: 100% from the base :host selector to only apply to gallery and quiet variants

sp-overlay: Fixed : external click registration behavior in the sp-overlay component. Programmatic clicks on elements outside of modal overlays now properly register and close the overlay, while user-initiated clicks are prevented from doing so.

sp-card: Enhanced the Card component's checkbox functionality with improved screen reader support and keyboard navigation.

Patch Changes

sp-progress-bar: Added: Deprecation warning for the over-background attribute.

sp-combobox: Replace the use of offsetWidth with a resizeObserver to avoid unecessary, performance-impacting layout reflows.

sp-styles: Bring the CJK font alias token fix from CSS #3883 4e3a120.

The --spectrum-cjk-font token was incorrectly mapped to the code font-family stack instead of --spectrum-cjk-font-family-stack. Thanks @byteakp!

sp-color-wheel: Fixed <sp-color-wheel> step attribute functionality for keyboard navigation. The step attribute now properly controls the increment size when using arrow keys to navigate the color wheel.

sp-switch: ### Fix down state colors for switch

Because the postcss-hover-media-feature plugin converts hover styles into a media query for devices that support hover, the hover styles were overriding any active/down state styles. We needed to target the active/down states of the switch with additional active state selectors, in order to ensure that the active state takes precedence over the hover state, maintaining the correct visual behavior of the switch component across different interaction states.

This fix should address hover + active state discrepancies in S1 and S2 foundations.

sp-contextual-help: Fixed a typo in the default info variant label from "Informations" to "Information".

Additionally, added package dependency for @spectrum-web-components/reactive-controllers@1.7.0.

sp-slider: Editable sliders will now reliably emit input events when interaction starts with the track.

sp-link: Fixed quiet variant links not showing keyboard focus state in Safari. Links with the quiet attribute now properly display focus indicators when navigating with keyboard, improving accessibility for keyboard users.

sp-progress-bar: Smooths the transition animation of indeterminate progress bar by overriding the incoming CSS, and positioning the animating fill element completely off of the progress bar track in both LTR and RTL languages. Before, the fill element was automatically starting on the track which led to a jarring animation loop.

sp-divider: Added: staticColor property to the Divider component, enabling programmatic control of the existing static color functionality.