useBreadcrumbs

Provides the behavior and accessibility implementation for a breadcrumbs component. Breadcrumbs display a heirarchy of links to the current page or resource in an application.

install	`yarn add @react-aria/breadcrumbs`
version	3.0.0-alpha.1
usage	`import {useBreadcrumbs, useBreadcrumbItem} from '@react-aria/breadcrumbs'`

View ARIA spec

W3C

API#

useBreadcrumbs<T>(props: AriaBreadcrumbsProps<T>): BreadcrumbsAriauseBreadcrumbItem(props: AriaBreadcrumbItemProps): BreadcrumbItemAria

Features#

Breadcrumbs provide a list of links to parent pages of the current page in heirarchical order. useBreadcrumbs and useBreadcrumbItem help implement these in an accessible way.

Support for mouse, touch, and keyboard interactions on breadcrumbs
Support for navigation links via <a> elements or custom element types via ARIA
Localized ARIA labeling support for landmark navigation region
Support for disabled breadcrumbs
Support for breadcrumbs as a heading

Anatomy#

Breadcrumbs consist of a navigation landmark element and a list of links. The last link represents the current page in the heirarchy, with the previous links representing the parent pages of the current page. Each of these parent links can be clicked, tapped, or triggered via the Enter key to navigate to that page. Optionally, breadcrumbs can be used in place of a page title, in which case the last breadcrumb acts as a heading.

useBreadcrumbs returns props to be spread onto the navigation element:

Name	Type	Description
`breadcrumbsProps`	`HTMLAttributes<HTMLDivElement>`	Props for the bradcrumbs navigation element.

useBreadcrumbItem returns props to spread onto the individual breadcrumb links:

Name	Type	Description
`breadcrumbItemProps`	`HTMLAttributes<HTMLDivElement>`	Props for the breadcrumb item link element.

Example#

This example displays a basic list of breadcrumbs using an HTML <nav> element, and a <ol> for the list of links. Each link is a span because we are handling the interactions locally via onPress. useBreadcrumbItem automatically handles exposing these spans as links to assistive technology.

The chevrons between each link are rendered using a span with aria-hidden="true" so that screen readers do not pick them up. You could also render them similarly using SVG icons, CSS :after, or other techniques.

The last link is non-interactive since it represents the current page. This is passed to the last breadcrumb item by cloning the element and adding the isCurrent prop.

function Breadcrumbs(props) {
  let {breadcrumbsProps} = useBreadcrumbs(props);
  let children = React.Children.toArray(props.children);

  return (
    <nav {...breadcrumbsProps}>
      <ol style={{display: 'flex', listStyle: 'none'}}>
        {children.map((child, i) => 
          React.cloneElement(child, {isCurrent: i === children.length - 1})
        )}
      </ol>
    </nav>
  )
}

function BreadcrumbItem(props) {
  let {breadcrumbItemProps} = useBreadcrumbItem({...props, elementType: 'span'});
  return (
    <li>
      <span
        {...breadcrumbItemProps}
        style={{
          color: 'dodgerblue',
          textDecoration: props.isCurrent ? null : 'underline',
          fontWeight: props.isCurrent ? 'bold' : null,
          cursor: props.isCurrent ? 'default' : 'pointer'
        }}>
        {props.children}
      </span>
      {!props.isCurrent &&
        <span aria-hidden="true" style={{padding: '0 5px'}}>{'›'}</span>
      }
    </li>
  );
}

<Breadcrumbs>
  <BreadcrumbItem onPress={() => alert('Pressed Folder 1')}>Folder 1</BreadcrumbItem>
  <BreadcrumbItem onPress={() => alert('Pressed Folder 2')}>Folder 2</BreadcrumbItem>
  <BreadcrumbItem>Folder 3</BreadcrumbItem>
</Breadcrumbs>

This example is similar to the previous one, except the individual breadcrumbs are native navigation links to other pages rather than handled by JavaScript.

function Breadcrumbs(props) {
  // Same as in the previous example...
}

function BreadcrumbItem(props) {
  let {breadcrumbItemProps} = useBreadcrumbItem(props);
  return (
    <li>
      <a
        {...breadcrumbItemProps}
        href={props.href}
        style={{
          color: 'dodgerblue',
          fontWeight: props.isCurrent ? 'bold' : null,
          cursor: props.isCurrent ? 'default' : 'pointer'
        }}>
        {props.children}
      </a>
      {!props.isCurrent &&
        <span aria-hidden="true" style={{padding: '0 5px'}}>{'›'}</span>
      }
    </li>
  );
}

<Breadcrumbs>
  <BreadcrumbItem href="/">Home</BreadcrumbItem>
  <BreadcrumbItem href="/react-aria">React Aria</BreadcrumbItem>
  <BreadcrumbItem>useBreadcrumbs</BreadcrumbItem>
</Breadcrumbs>

Breadcrumbs as a heading#

If you use breadcrumbs in the context where a heading would normally be used, you can pass the isHeading prop to the breadcrumb items and the last breadcrumb will be exposed as a heading to assistive technology. headingAriaLevel can also be used to set the level of that heading.

function Breadcrumbs(props) {
  let {breadcrumbsProps} = useBreadcrumbs(props);
  let children = React.Children.toArray(props.children);

  return (
    <nav {...breadcrumbsProps}>
      <ol style={{display: 'flex', listStyle: 'none'}}>
        {children.map((child, i) => 
          React.cloneElement(child, {
            isCurrent: i === children.length - 1,
            isHeading: true,
            headingAriaLevel: 3
          })
        )}
      </ol>
    </nav>
  );
}

function BreadcrumbItem(props) {
  // Same as in the previous example...
}

<Breadcrumbs>
  <BreadcrumbItem href="/">Home</BreadcrumbItem>
  <BreadcrumbItem href="/react-aria">React Aria</BreadcrumbItem>
  <BreadcrumbItem>useBreadcrumbs</BreadcrumbItem>
</Breadcrumbs>

Name	Type	Description
`children`	`ReactElement<ItemProps<T>> \| ReactElement<ItemProps<T>>[]`	The breadcrumb items.
`isHeading`	`boolean`	Whether the breadcrumbs are used as a heading element.
`headingAriaLevel`	`number`	Sets the aria-level attribute of the last item, but only if `isHeading` is true.
`isDisabled`	`boolean`	Whether the Breadcrumbs are disabled.
`onAction`	`(key: Key) => void`	Called when an item is acted upon (usually selection via press).
`id`	`string`
`tabIndex`	`number`
`role`	`string`
`aria-label`	`string`	Defines a string value that labels the current element.
`aria-labelledby`	`string`	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	Identifies the element (or elements) that describes the object.
`aria-controls`	`string`	Identifies the element (or elements) whose contents or presence are controlled by the current element.
`aria-owns`	`string`	Identifies an element (or elements) in order to define a visual, functional, or contextual parent/child relationship between DOM elements where the DOM hierarchy cannot be used to represent the relationship.
`aria-hidden`	`boolean \| 'false' \| 'true'`	Indicates that the element is perceivable but disabled, so it is not editable or otherwise operable.

Name	Type	Description
`children`	`ReactNode`	Rendered contents of the item or child items.
`title`	`ReactNode`	Rendered contents of the item if `children` contains child items.
`textValue`	`string`	A string representation of the item's contents, used for features like typeahead.
`aria-label`	`string`	An accessibility label for this item.
`childItems`	`Iterable<T>`	A list of child item objects. Used for dynamic collections.
`hasChildItems`	`boolean`	Whether this item has children, even if not loaded yet.
`uniqueKey`	`Key`	A unique key for this item.

Name	Type	Description
`breadcrumbsProps`	`HTMLAttributes<HTMLDivElement>`	Props for the bradcrumbs navigation element.

Name	Type	Description
`elementType`	`string`	The HTML element used to render the breadcrumb link, e.g. "a", or "span".
`isCurrent`	`boolean`	Whether the breadcrumb item represents the current page.
`aria-current`	`'page' \| 'step' \| 'location' \| 'date' \| 'time' \| boolean \| 'true' \| 'false'`	The type of current location the breadcrumb item represents, if `isCurrent` is true.
`isHeading`	`boolean`	Whether the breadcrumbs are used as a heading element.
`isDisabled`	`boolean`	Whether the breadcrumb item is disabled.
`headingAriaLevel`	`number`	The aria-level for the heading element if `isHeading` and `isCurrent` are true.
`children`	`ReactNode`	The contents of the breadcrumb item.
`onPress`	`(e: PressEvent) => void`	Handler that is called when the press is released over the target.
`onPressStart`	`(e: PressEvent) => void`	Handler that is called when a press interaction starts.
`onPressEnd`	`(e: PressEvent) => void`	Handler that is called when a press interation ends, either over the target or when the pointer leaves the target.
`onPressChange`	`(isPressed: boolean) => void`	Handler that is called when the press state changes.
`onPressUp`	`(e: PressEvent) => void`	Handler that is called when a press is released over the target, regardless of whether it started on the target or not.
`id`	`string`
`tabIndex`	`number`
`role`	`string`
`aria-label`	`string`	Defines a string value that labels the current element.
`aria-labelledby`	`string`	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	Identifies the element (or elements) that describes the object.
`aria-controls`	`string`	Identifies the element (or elements) whose contents or presence are controlled by the current element.
`aria-owns`	`string`	Identifies an element (or elements) in order to define a visual, functional, or contextual parent/child relationship between DOM elements where the DOM hierarchy cannot be used to represent the relationship.
`aria-hidden`	`boolean \| 'false' \| 'true'`	Indicates that the element is perceivable but disabled, so it is not editable or otherwise operable.

Name	Type	Description
`type`	`'pressstart' \| 'pressend' \| 'pressup' \| 'press'`	The type of press event being fired.
`pointerType`	`PointerType`	The pointer type that triggered the press event.
`target`	`HTMLElement`	The target element of the press event.
`shiftKey`	`boolean`	Whether the shift keyboard modifier was held during the press event.
`ctrlKey`	`boolean`	Whether the ctrl keyboard modifier was held during the press event.
`metaKey`	`boolean`	Whether the meta keyboard modifier was held during the press event.

'mouse'
  | 'pen'
  | 'touch'
  | 'keyboard'
  | 'virtual'