Migration Information

For teams migrating from the V1 to V2 component, please refer to the migration guide for changes to the component.

Component Guide

import { Breadcrumbs } from '@uhg-abyss/web/ui/Breadcrumbs';

Usage

Integrate Breadcrumbs with Router by using Links and Router routes. The Breadcrumbs component displays breadcrumbs based on the URL of the current location. Breadcrumbs are used for navigation through multi-level pages. The example below simulates this behavior.

Title

The title prop accepts either a string or a function. For static titles, use a string. For dynamic titles, provide a function that accepts the router URL parameters and returns a string.

To use URL parameters, utilize React Router's dynamic path segmentsopens in a new window syntax in the path prop of the Router.Route and the href prop of the breadcrumb.

Requires React Router v6

The use of dynamic titles using dynamic path segments requires React Router v6. As such, the example below is not a live example, as our docs site is using v5.

() => {
  return (
    <RouterProvider>
      <Breadcrumbs
        items={[
          { title: 'Home', href: '/' },
          {
            title: ({ component }) => {
              return `Component: ${component || 'None'}`;
            },
            href: '/web/ui/:component',
          },
        ]}
      />

      <Router.Routes>
        <Router.Route path="/" element={<Page />} />
        <Router.Route path="/web/ui/:component" element={<Page />} />
      </Router.Routes>
    </RouterProvider>
  );
};

Variant

Use the variant prop to change the styling of the Breadcrumbs. The possible options are 'default', and 'alt'. The default is set to 'default'.

Comparator

The comparator prop takes in a custom callback function to directly handle the determination of which breadcrumbs are displayed. This function must match the following interface:

comparator?: (href: string, location: Location) => boolean;

href is the href of the breadcrumb to compare and location is the current location object.

If no function is specified, the default comparison is between the breadcrumb item href and the current location pathname.

Mobile width

On screens less than 744px wide, the Breadcrumbs will only display the previous page title. Resize the window to see the change!

In both mobile and desktop layouts, Breadcrumbs keeps semantic ordered-list markup so assistive technologies can announce the trail consistently.

Hide breadcrumb items

Use hide on an item to exclude it from the rendered breadcrumb trail. The default is false.

Tip

This is particularly helpful for adhering to Abyss design guidelinesopens in a new window. We strongly recommend hiding the root breadcrumb (e.g., "Home") when there is an equivalent link in the page's global navigation to avoid duplicate links.

onClick

Use the onClick prop to provide a function that is called when a breadcrumb is clicked. The function receives two arguments: the event and the data of the clicked breadcrumb.

Breadcrumbs Props

Name	Type	Default	Required	Description
className	string | undefined			CSS class name to apply to each element within the component
comparator	((href: string, location: Location) => boolean) | undefined			Callback function used to determine which breadcrumbs should be displayed Note: If this no value is given for this prop, the default comparison is between the Breadcrumb item href and the current location pathname.
css	CSSProperties | Partial<Record<"abyss-breadcrumbs-root" | "abyss-breadcrumbs-breadcrumb", CSSProperties>> | undefined			Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation See CSS Prop Styling for more information
data-testid	string | undefined			Suffix used to create a unique ID used for automated testing See Component Testing for more information
disableDefaultProviderProps	boolean | undefined	false		If set to true, the component will not use the DefaultPropsProvider values. If you aren’t using the DefaultPropsProvider, this prop can be ignored.
hiddenFrom	Breakpoint | undefined			When defined, the component is hidden once the screen width reaches the specified breakpoint.
items	BreadcrumbItem[]			List of the individual breadcrumb items
onClick	((e: MouseClickEvent<HTMLElement>, data: { title: string; href: string; }) => void) | undefined			Function to be called when a breadcrumb is clicked
slotProps	BreadcrumbsSlotPropsMap | undefined
variant	"default" | "alt" | undefined	'default'		The visual variant
visibleFrom	Breakpoint | undefined			When defined, the component is hidden until the screen width reaches the specified breakpoint.

Breadcrumbs Classes

Class Name	Description
.abyss-breadcrumbs-breadcrumb	Breadcrumb rendered in the trail
.abyss-breadcrumbs-root	Breadcrumbs list root element

A breadcrumb trail consists of a list of links to the parent pages of the current page in hierarchical order. It helps users find their place within a website or web application. Breadcrumbs are often placed horizontally before a page's main content. Useful links to learn more about the WAI-ARIA design pattern for breadcrumbs: Breadcrumb WAI-ARIA exampleopens in a new window | ARIA Currentopens in a new window.

Adheres to the Breadcrumb WAI-ARIA design patternopens in a new window.

Component Tokens

Tip

Click on the token row to copy the token to your clipboard.

Breadcrumbs Tokens

Search tokens

Token Name	Value
breadcrumbs.color.text.current.regular	#323334
breadcrumbs.color.text.current.alt	#FFFFFF
breadcrumbs.color.icon.regular	#323334
breadcrumbs.color.icon.alt	#FFFFFF
breadcrumbs.sizing.all.icon.separator	16px
breadcrumbs.spacing.gap.horizontal.container	4px