Breadcrumbs

Breadcrumbs are a secondary form of navigation that allow users to keep track and maintain awareness of their location as they move through different pages, folders, or files.

GitHubStorybook
yarn add @workday/canvas-kit-preview-react
Sources
GitHubStorybook
Install
yarn add @workday/canvas-kit-preview-react

Anatomy

Image of a Breadcrumbs with annotation markers.

  1. Root Page: The root page grounds the trail as users navigate to subsequent pages.
  2. Breadcrumb Pages: Each page has its own label. Pages are styled as Hyperlink Text and should be prepended by the word ‘Page’, ie: Page (#).
  3. Current Page/Folder: All users should be aware of which page they are currently viewing. It is not clickable.
  4. Divider: The divider inherits the styling of our Icon Only Tertiary Button Variant, but it is not clickable. Use the Chevron System Icon.
  5. Truncated Breadcrumbs: The Breadcrumb trail will truncate after the Breadcrumb hits a certain width. Truncated pages hide within an Icon Only Tertiary Button Variant styled with a Related Actions System Icon. It should be clear to a screen reader user that there are additional pages that are truncated.
  6. Menu: This is the container that houses truncated pages. Use our Menu component. Screen reader users should be able to navigate through and select a page within the menu.

Usage Guidance

  • Breadcrumbs help to orient the user and keep track of their location as they navigate through a site’s information hierarchy.
  • The component should be used to supplement the primary or main navigation - not replace them.
  • Breadcrumb trails always start with a root page that subsequent pages trace back to.
  • Using Breadcrumbs should enable users to backtrack and jump to previous pages with ease.

Placement

  • Breadcrumbs are represented as a trail of links anchored at the top left of a page, above the page title but below the header.
  • The position of Breadcrumbs should not move as the user navigates through different pages.

Truncation

  • Although truncation behavior is built into the component, be thoughtful about the width of each page title and how to collapse and truncate page items.
  • Page titles and items will truncate after hitting a specified width (all items are set to truncate at 350px, but can be customized).
  • If truncation is required, truncated items will collapse into an Icon Only Tertiary Button Variant, placed in-between the first item (root page) and last item (current page).
  • Users can access truncated pages by clicking into the collapsible Icon Only Tertiary Button Variant and selecting the desired page within the Menu.

Responsive Behavior

  • On responsive or smaller screens, leverage the collapsible menu to shorten the Breadcrumb trail.
  • Only truncate the root page if absolutely necessary.
  • The current page is always visible and should never collapse into the overflow Menu.

When to Use

  • Use Breadcrumbs when users must navigate through a complex site or product.
  • Use Breadcrumbs to track hierarchical navigation.

When to Use Something Else

  • Use other components for primary navigation. Breadcrumbs are used to supplement a global or primary navigation.
  • Consider removing Breadcrumbs altogether if you have a flat hierarchy that is only 1 or 2 levels deep.

Examples

Basic Example

Breadcrumbs.List is a styled unordered list <ul> with no additional behaviors. Use this when you are not concerned about collapsing the list of breadcrumb items into a dropdown menu at a specified width.

Accessibility is built into Breadcrumbs components in a way that allows you to create an inclusive experience with little additional configuration. The only ARIA label you'll need to add is the aria-label for Breadcrumbs.Nav as seen in the example. And all links require hrefs to be properly identified. All other accessible attributes are baked into the components.

Collapsible List

Breadcrumbs.CollapsibleList is built on top of Breadcrumbs.List. It provides additional functionality to collapse list items into a dropdown menu at a specified width.

In addition to adding aria-label to Breadcrumbs.Nav and identifying all links with an href, you'll need to add buttonAriaLabel to Breadcrumbs.CollapsibleList.

Right-to-Left (RTL)

Breadcrumbs has bidirectional support out of the box. That means outside of setting the content direction in your application's Canvas theme, you don't need to do anything else to make it work. All you need to supply is the translated text for items and ARIA labels.

Component API

Usage

Breadcrumbs.Nav a styled <nav> element. It has no intrinsic state or behaviors.

Props

This component also supports all native HTMLElement props.

NameTypeDefaultDescription
aria-label*stringThe accessibility label to indicate the type of navigation. Suggested value: "breadcrumb"

Usage

Breadcrumbs.List component is a styled, unordered list (<ul>) with no additional behaviors. Use this when you're not concerned about collapsing the list of breadcrumb items into a dropdown menu at a specified width.

Props

Breadcrumbs.List has no component-specific props. However, it supports all native <ul> element props.


Usage

Breadcrumbs.CollapsibleList is built on top of Breadcrumbs.List. It provides additional functionality to collapse list items into a dropdown menu at a specified width.

The maxWidth prop sets the point to collapse. If the length of the list exceeds that value, items will be collapsed into a dropdown menu. Note that the first (root) item and last (current) items in the list will never be collapsed.

Handling Custom Dropdown Button Icons

By default the icon for the dropdown button is relatedActionsIcon. However, you can set this to any Canvas System Icon with the buttonIcon prop. Please consult the Canvas team if you decide to do this, as we'd like to keep breadcrumb navigation as consistent as possible.

Props

This component also supports all native <ul> element props.

NameTypeDefaultDescription
buttonAriaLabel*stringThe accessibility label for the dropdown menu button. Suggested value: "more links"
maxWidth*numberThe max-width before the list should collapse and render a dropdown menu
buttonIconCanvasSystemIcon | undefinedrelatedActionsIconThe Canvas System Icon for the button

Usage

Breadcrumbs.ListItem is a styled <li> element that contains a SystemIcon separator.

Props

Breadcrumbs.ListItem has no component-specific props. However, it supports all native <li> element props.


Usage

Breadcrumbs.Link is a styled <a> element that also renders a tooltip if the text is truncated. The built-in truncation + tooltip functionality provides an easy-to-use, accessible feature for managing the length of link text. The maxWidth is set to 350px by default and can be adjusted as needed. Note that tooltips will only render when text is truncated. Here's an example with the maxWidth set to 150px.

Small Plates & Appetizers
Handling Redirects

Breadcrumbs.Link defaults to redirecting with an href, meaning the page will hard-redirect when the link is clicked. However, if you're in a single-page application (SPA) environment, you might want to use the internal SPA router instead. You can override this hard-redirect with the onAction prop. Note that onAction will not block any onClick if provided. Below is an example using the history package.

import * as React from 'react';
// using the history package
import {createBrowserHistory} from 'history';
import {Breadcrumbs} from '@workday/canvas-kit-preview-react/breadcrumbs';
// this is likely being done at the root of your application and not inside this component.
const history = createBrowserHistory();
const handleClick = (event: React.MouseEvent<HTMLAnchorElement, MouseEvent>) => {
// handle any click side-effects here
console.log('click event', event);
}
const handleRedirect = (href: string) => {
// redirect using the internal SPA router
history.push(href);
}
return (
<Breadcrumbs.Link
href="/account"
onAction={handleRedirect}
onClick={handleClick}
>
Account
</Breadcrumbs.Link>;
)

Props

This component also supports all native <a> element props.

NameTypeDefaultDescription
href*stringThe href url of the anchor tag
maxWidthnumber | undefined350pxThe max-width of the link text
onAction((href: string) => void) | undefinedA handler function for overriding hard-redirects with links

Usage

Breadcrumbs.CurrentItem is a styled <li> element also renders a tooltip if the text is truncated. The built-in truncation + tooltip functionality provides an easy-to-use, accessible feature for managing the length of link text. The maxWidth is set to 350px by default and can be adjusted as needed. Normally, this is a non-focusable element. But when truncated, it sets the tabIndex to 0 to enable the tooltip to appear on keyboard focus. Note that tooltips will only render when text is truncated. Here's an example with the maxWidth set to 100px.

  • Foccacia Genovese
  • Props

    This component also supports all native <li> element props.

    NameTypeDefaultDescription
    maxWidthnumber | undefined350pxThe max-width of the text

    Specifications

    GivenWhenThen
    the Basic example is rendered
      • it should not have any axe errors
      the Basic example is rendered
        • it should have a role of "navigation" on the <nav> element
        the Basic example is rendered
          • it should have an aria-label on the <nav> element
          the Basic example is rendered
            • it should have a role of "list" on the <ul> element
            the Basic example is rendered
            • a breadcrumb link is focused
            • it should show tooltips for truncated link items
            the Basic example is rendered
            • a breadcrumb link is focused
            • it should not show tooltips for truncated link items
            the Basic example is rendered
            • the last breadcrumb (current item) is focused
            • it should show a tooltip for the truncated text
            the Collapsible List example is rendered
              • it should not have any axe errors
              the Collapsible List example is rendered
                • it should have aria-expanded set to "false" on the dropdown button
                the Collapsible List example is rendered
                  • it should have aria-haspopup set to "true" on the dropdown button
                  the Collapsible List example is rendered
                    • it should have aria-controls set to "menu" on the dropdown button
                    the Collapsible List example is rendered
                    • the dropdown button is clicked
                    • it should toggle the button's aria-expanded attribute
                    the Collapsible List menu is rendered
                      • it should not have any axe errors
                      the Collapsible List menu is rendered
                        • it should have role set to "menu" on the dropdown menu
                        the Collapsible List menu is rendered
                          • it should have role set to "menuitem" for dropdown item link
                          the Collapsible List menu is rendered
                          • the dropdown menu is toggled with a keypress
                          • it should set focus to the first menu item
                          the Collapsible List menu is rendered
                          • the first menu item is focused
                          • it should toggle focus to the second menu item on down keypress
                          the Collapsible List menu is rendered
                          • the last menu item is focused
                          • it should roll the focus back to the first menu item on down keypress
                          the Collapsible List menu is rendered
                          • the down arrow key is pressed on the dropdown menu
                          • it should toggle focus to the next menu item on down keypress
                          the Collapsible List menu is rendered
                          • the right arrow key is pressed on the dropdown menu
                          • it should toggle focus to the next menu item
                          the Collapsible List menu is rendered
                          • the right arrow key is pressed on the dropdown menu
                          • it should roll the focus back from the last menu item to the first menu item
                          the Collapsible List menu is rendered
                          • the up arrow key is pressed on the dropdown menu
                          • it should toggle focus to the previous list item
                          the Collapsible List menu is rendered
                          • the up arrow key is pressed on the dropdown menu
                          • it should return focus from the first menu item to the dropdown button
                          the Collapsible List menu is rendered
                          • the left arrow key is pressed on the dropdown menu
                          • it should toggle focus to the previous menu item
                          the Collapsible List menu is rendered
                          • the left arrow key is pressed on the dropdown menu
                          • it should return focus from the first menu item to the dropdown button
                          the Collapsible List menu is rendered
                          • the escape key is pressed on the dropdown menu
                          • it should return focus to the dropdown menu button
                          Source: Breadcrumbs.spec.ts

                          Accessibility Guidelines

                          • Breadcrumbs are navigational so the component should be encapsulated within a <nav> region.
                          • The <nav> region must have a uniquely descriptive accessible name for screen reader users to be able to distinguish Breadcrumbs among other <nav> regions on the page. (e.g. aria-label=”breadcrumb”)
                          • Breadcrumb links must be semantic <a> tags, with valid href attributes to ensure keyboard and screen reader accessibility.
                          • Constructing the list of links inside of a semantic unordered list markup with parent <ul> and child <li> tags will help provide further context to users about a given Breadcrumb’s position in a list, out of the total number of Breadcrumbs.
                          • All foreground text must meet a contrast ratio of 4.5:1 in relation to its background color.
                          • For accessibility guidelines related to the Breadcrumbs overflow menu, refer to our Menu component. For general accessibility considerations, refer to the Accessibility Guide.

                          Content Guidelines

                          Breadcrumb titles should inherit the same name as the page or product title the user has navigated to. When writing content for Breadcrumbs, refer to our Content Style Guide.

                          Can't Find What You Need?

                          Check out our FAQ section which may help you find the information you're looking for.

                          FAQ Section