Breadcrumbs

Anatomy

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 includes a container Breadcrumbs component and the following subcomponents which can be composed in a variety of ways: Breadcrumbs.List, Breadcrumbs.Item, Breadcrumbs.CurrentItem and Breadcrumbs.Link.

Accessibility is built into Breadcrumbs in a way that allows you to create an inclusive experience with little additional configuration. As seen in the example below, you don't need to pass any accessibility attributes, because they are baked into the component. You only need to add aria-label attribute to a nav component through a aria-label prop of Breadcrumbs.

Note that all links require an href to be properly identified.

Overflow Breadcrumbs

Breadcrumbs is a responsive component based on the width of its container. If the rendered links exceed the width of the Breadcrumbs.List, an overflow menu will be rendered. This only works against the dynamic API where you give the BreadcrumbsModel an array of items to be rendered. The dynamic API handles the React key for you based on the item's identifier. The dynamic API requires either an id on each item object or a getId function that returns an identifier based on the item. The example below uses an id property on each item.

The dynamic API takes in any object, but since nothing is known about your object, a render prop is necessary to instruct a list how it should render.

Truncating a Link

Breadcrumbs.Link is a styled <a> element that also renders a tooltip if the text is truncated. The built-in truncation and 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. The example below uses a maxWidth of 150px.

Item Truncation

Breadcrumbs.CurrentItem is a styled <li> element that also renders a tooltip if the text is truncated. The built-in truncation and tooltip functionality provides an easy-to-use, accessible feature for managing the length of the text. The maxWidth is set to 350px by default and can be adjusted as needed. Normally, this is a non-focusable element; when truncated, however, 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. The example below uses a maxWidth of 100px.

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.

Handling Redirects

Breadcrumbs.Link defaults to redirecting with an href, which means 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 that behavior with a custom onClick handler that blocks the default behavior of the event and passes along the link path to your SPA router. Most of our consumers use react-router-dom for managing SPA routing, so below is an example of how to do this in V5 and V6 of react-router-dom.

// React Router DOM V5 API
import {useHistory} from 'react-router-dom';
import {Breadcrumbs} from '@workday/canvas-kit-react/breadcrumbs';
...
const history = useHistory();
const handleClick = (event: React.MouseEvent<HTMLAnchorElement, MouseEvent>, link?: string) => {
      event.preventDefault();
    // if no link is provided, default to the current path
    history.push(link || window.location.pathname);
}
return (
  <Breadcrumbs.Link href="/account" onClick={handleClick}>
    Account
  </Breadcrumbs.Link>
);

// React Router DOM V6 API
import {useNavigate} from 'react-router-dom';
import {Breadcrumbs} from '@workday/canvas-kit-react/breadcrumbs';
...
const navigate = useNavigate();
const handleClick = (event: React.MouseEvent<HTMLAnchorElement, MouseEvent>, link?: string) => {
      event.preventDefault();
    // if no link is provided, default to the current path
    navigate(link || window.location.pathname);
}
return (
  <Breadcrumbs.Link href="/account" onClick={handleClick}>
    Account
  </Breadcrumbs.Link>
);

Component API

<Breadcrumbs aria-label="Breadcrumbs">
  <Breadcrumbs.List>
    <Breadcrumbs.Item>
      <Breadcrumbs.Link href="/docs">Docs</Breadcrumbs.Link>
    <Breadcrumbs.Item>
    <Breadcrumbs.Item>
      <Breadcrumbs.Link href="/docs/components">Components</Breadcrumbs.Link>
    <Breadcrumbs.Item>
    <Breadcrumbs.CurrentItem>
      <Breadcrumbs.Link href="/docs/components/breadcrumbs">Breadcrumbs</Breadcrumbs.Link>
    <Breadcrumbs.CurrentItem>
  <Breadcrumbs.List>
</Breadcrumbs>

<Breadcrumbs items={[]} aria-label="Breadcrumbs">
  {Child components}
</Breadcrumbs>

const model = useBreadcrumbsModel({
  items: [],
});

<Breadcrumbs model={model} aria-label="Breadcrumbs">
  {Child components}
</Breadcrumbs>;

// without overflow
<Breadcrumbs.List>{Breadcrumbs.Items}</Breadcrumbs.List>

// with overflow
<Breadcrumbs.List overflowButton={<Breadcrumbs.OverflowButton aria-label="More links" />}>
  {Breadcrumbs.Items}
</Breadcrumbs.List>

import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

return (
 <Element
   {...mergeStyles(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

<Breadcrumbs.Item maxWidth={200}>
  <Breadcrumbs.Link href="/docs">Docs</Breadcrumbs.Link>
</Breadcrumbs.Item>

<Breadcrumbs.Item>First Action</Breadcrumbs.Item>

import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

return (
 <Element
   {...mergeStyles(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

<Breadcrumbs.CurrentItem maxWidth={200}>
  Current Item Text
</Breadcrumbs.CurrentItem>

<Text typeLevel="body.small">Small body text</Text>

<Text variant="error" typeLevel="subtext.large">Error text</Text>

import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

return (
 <Element
   {...mergeStyles(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

<Breadcrumbs.List
  overflowButtonProps={{
    'aria-label': 'More links',
    onClick={handleOverflowButtonClick}
  }}
>

import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

return (
 <Element
   {...mergeStyles(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

<Breadcrumbs.Menu.Popper>
  <Breadcrumbs.Menu.Card>
    <Breadcrumbs.Menu.List>
      {(item: MyActionItem) => <Breadcrumbs.Menu.Item>{item.text}</Breadcrumbs.Menu.Item>}
    </Breadcrumbs.Menu.List>
  </Breadcrumbs.Menu.Card>
</Breadcrumbs.Menu.Popper>

Specifications

Accessibility Guidelines

Keyboard Interaction

Each link in the breadcrumbs must have a focus indicator that is highly visible against the background and against the non-focused state. Refer to Accessible Colors for more information.

Breadcrumbs must support the following keyboard interactions:

• Tab: Focuses each link in the breadcrumb navigation
• Enter: Activates the currently focused link, or expands the truncated breadcrumb overflow menu
• Up Arrow or Down Arrow: Navigates up or down the truncated breadcrumb menu

Screen Reader Interaction

Breadcrumbs must communicate the following to users:

• Breadcrumbs are a navigation landmark, that can be distinguished from other site navigation provided on a page
• How many breadcrumb links are shown
• Which breadcrumb link represents the current page
• There is a menu of “more links” when the breadcrumb component is truncated.

Design Annotations Needed

No annotations required for Breadcrumbs.

Implementation Markup Needed

• If the last element in the Breadcrumbs component is a link, an aria-current="page" attribute must be added to the link.
• [Included in component] Breadcrumb container must be a <nav> element with an aria-label string “Breadcrumbs”.
• [Included in component] Inside of the <nav> element, breadcrumb links must be structured with <ul> and <li> list markup.
• [Included in component] Chevron icons are decorative and should be hidden from screen readers.
• [Included in component] Truncated breadcrumbs use an icon button with an aria-label string set to “More links” and an aria-haspopup=”true” attribute to signal an attached menu will appear.

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.