Element Breadcrumb

Element React - Breadcrumb

Breadcrumbs allow users to make selection from a range of values.

They're often used to track a users location within an application, like a more user friendly URL. The user can click on any of the breadcrumbs to get back to that location inside the application.

Example Usage

Style

@use '@element/react/Breadcrumb';

JSX

Props

PropRequired?TypeDefaultDescription
childrentrueReact.ReactNode-Label of the Breadcrumb
tofalsestring | any-Destination that clicking the breadcrumb should navigate to. This value is automatically passed to the to and href props of linkComponent if it's passed
leadingIconfalseReact.ReactNode-Icon to show to the left of the breadcrumb label
trailingIconfalseReact.ReactNode-Icon to show to the right of the breadcrumb label
isDisabledfalseboolean-True renders this breadcrumb as text instead of a link
linkComponentfalseany-React component to render instead of a standard anchor <a> tag
linkPropsfalseobject{}Object containing props that should be passed to the linkComponent once it is rendered

Variants

With Icons

You can add either leading or trailing icons to the Breadcrumbs via the leadingIcon and trailingIcon props respectively.

Collapsed Breadcrumbs

You can limit the number of breadcrumbs shown, automatically collapsing other breadcrumbs, by passing the maxItems prop to the BreadcrumbGroup.

The user can then click on the collapsed ellipsis to view all current breadcrumbs.

You can also control which breadcrumbs get automatically collapsed by additionally passing the collapseAt prop to the BreadcrumbGroup.

Integration with React Router

It's often necessary to integrate any navigation component with a routing library like React Router. The Element Breadcrumb component was built with such libraries in mind.

The following examples are specific to React Router, but the ideas can be applied to any routing library.

Using Link

React Router provides a Link component that can be used to navigate via React Router around your application. You can pass this Link component to the linkComponent prop of either BreadcrumbGroup or Breadcrumb.

import {Link} from 'react-router-dom'

function Foo(props) {
  return (
    <BreadcrumbGroup ariaLabel='REPLACE-ME' linkComponent={Link}>
      <Breadcrumb to='/'>Home</Breadcrumb>
      <Breadcrumb to='/pages/two'>Second level</Breadcrumb>
      <Breadcrumb to='/pages/three'>Third level</Breadcrumb>
      <Breadcrumb to='/pages/four'>Current</Breadcrumb>
    </BreadcrumbGroup>
  )
}

The to prop of the Breadcrumb component is automatically passed to React Router's Link component, but if you also want to pass other props to it, you can do so via the linkProps prop of either BreadcrumbGroup or Breadcrumb.

import React, {useRef} from 'react'
import {Link} from 'react-router-dom'

function Foo(props) {
  const linkRef = useRef()

  console.log(linkRef.current)

  return (
    <BreadcrumbGroup
      ariaLabel='REPLACE-ME'
      linkComponent={Link}
      linkProps={{replace: true}}
    >
      <Breadcrumb linkProps={{title: 'Home', innerRef: linkRef}} to='/'>
        Home
      </Breadcrumb>
      <Breadcrumb
        to={{
          pathname: '/courses',
          search: '?sort=name',
          hash: '#the-hash',
          state: {fromDashboard: true},
        }}
      >
        Courses
      </Breadcrumb>
      <Breadcrumb>Current</Breadcrumb>
    </BreadcrumbGroup>
  )
}

Using onClick

Just like you would expect, you can also pass an onClick prop to any Breadcrumb. Using that, you can make use of React Router's useHistory hook.

import {Link, useHistory} from 'react-router-dom'
import {Breadcrumb, BreadcrumbGroup} from '@element/react'

function Foo(props) {
  const history = useHistory()

  return (
    <BreadcrumbGroup ariaLabel='REPLACE-ME'>
      <Breadcrumb onClick={() => history.push('/')}>Home</Breadcrumb>
      <Breadcrumb>Current</Breadcrumb>
    </BreadcrumbGroup>
  )
}

Helper Components

BreadcrumbGroup

The BreadcrumbGroup groups individual breadcrumbs together, places dividers between them, and makes decisions about the state of each breadcrumb based on the other breadcrumbs. For example, BreadcrumbGroup determines if any of the breadcrumbs should be collapsed, and if so which of them should collapse.

PropRequired?TypeDefaultDescription
ariaLabeltruestring-aria-label for the breadcrumb navigation. See the Accessibility section
maxItemsfalsenumber-Maximum number of breadcrumbs to show at one time. Any additional breadcrumbs will be automatically collapsed. Note that the collapsed ellipsis itself counts as a breadcrumb
collapseAtfalse'left' | 'left-middle' | 'middle' | 'right''middle'Determines which part of the breadcrumb trail will be automatically collapsed
allowExpansionfalsebooleantrueTrue allows the user to click on the collapsed ellipsis to expand and show all breadcrumbs
linkComponentfalseany-React component to render for all breadcrumbs instead of a standard anchor <a> tag. Passed through to all Breadcrumb children
linkPropsfalseobject{}Object containing props that should be passed to the linkComponent for all breadcrumbs once they are rendered. Passed through to all Breadcrumb children

Accessibility

(WAI-ARIA: https://www.w3.org/TR/wai-aria-practices/#breadcrumb)

Be sure to pass the ariaLabel prop to add an aria-label description on the nav element surrounding each breadcrumb group. A usage specific label is the most helpful.

The accessibility of this component relies on:

  • The set of links is structured using an ordered list (<ol> element).
  • To prevent screen reader announcement of the visual separators between links, they are hidden with aria-hidden.
  • A nav element labeled with aria-label identifies the structure as a breadcrumb trail and makes it a navigation landmark so that it is easy to locate.