Breadcrumbs

Breadcrumbs show hierarchy and navigational context for a user’s location within an application.

Example#

<Breadcrumbs>
  <Item uniqueKey="Folder 1">Folder 1</Item>
  <Item uniqueKey="Folder 2">Folder 2</Item>
  <Item uniqueKey="Folder 3">Folder 3</Item>
</Breadcrumbs>

Content#

Breadcrumbs accept as list of children, each with a uniqueKey prop.

It is required that the children are Item components from the @react-stately/collections library.

function Example() {
  return (
    <Breadcrumbs>
      <Item uniqueKey="Folder 1">Folder 1</Item>
      <Item uniqueKey="Folder 2">Folder 2</Item>
      <Item uniqueKey="Folder 3">Folder 3</Item>
    </Breadcrumbs>
  );
}

In order to identify children when a user takes an action on a item, each child needs to have a uniqueKey prop. See Events for more information.

Internationalization#

In order to internationalize Breadcrumbs, the strings of all child items should be localized.

Events#

Use the onAction prop as a callback to handle press events on items. The uniqueKey prop from the selected item will be passed into the callback.

function Example() {
  let folders = [
    {id: 1, label: 'Folder 1'},
    {id: 2, label: 'Folder 2'},
    {id: 3, label: 'Folder 3'}
  ];
  let [folderId, setFolderId] = React.useState();
  return (
    <div>
      <Breadcrumbs onAction={(a) => setFolderId(a)}>
        {folders.map(f => <Item key={f.id} uniqueKey={f.id}>{f.label}</Item>)}
      </Breadcrumbs>
      <p>Last Selected Folder: {folderId}</p>
    </div>
  );
}

Props#

Visual options#

Size#

The small size is useful when available space is limited.

<Breadcrumbs size="S">
  <Item uniqueKey="Folder 1">Folder 1</Item>
  <Item uniqueKey="Folder 2">Folder 2</Item>
</Breadcrumbs>

The medium size is the default.

<Breadcrumbs size="M">
  <Item uniqueKey="Folder 1">Folder 1</Item>
  <Item uniqueKey="Folder 2">Folder 2</Item>
</Breadcrumbs>

The large size places emphasis on the selected item as a page title or heading.

<Breadcrumbs size="L">
  <Item uniqueKey="Folder 1">Folder 1</Item>
  <Item uniqueKey="Folder 2">Folder 2</Item>
</Breadcrumbs>

Heading#

Use the isHeading prop to add a role of "heading" to the highlighted item. If a change to the aria-level is required, use the headingAriaLevel prop.

<Breadcrumbs isHeading headingAriaLevel={2}>
  <Item uniqueKey="Folder 1">Folder 1</Item>
  <Item uniqueKey="Folder 2">Folder 2</Item>
  <Item uniqueKey="Folder 3">Folder 3</Item>
</Breadcrumbs>

Visible items#

Breadcrumbs truncate by default to a maximum of 4 items visible.

If using maxVisibleItems="auto", truncation of breadcrumb items begins when there is not enough room to display all items in the parent container.

In order to manually control the truncation, use the maxVisibleItems prop.

<Breadcrumbs maxVisibleItems={2}>
  <Item uniqueKey="Folder 1">Folder 1</Item>
  <Item uniqueKey="Folder 2">Folder 2</Item>
  <Item uniqueKey="Folder 3">Folder 3</Item>
</Breadcrumbs>

Root context#

Some applications find that displaying the root item is useful for orienting users. This variation keeps the root visible when other items are truncated into the menu.

<View overflow="hidden" width="200px">
  <Breadcrumbs showRoot maxVisibleItems="auto">
    <Item uniqueKey="Folder 1">Folder 1</Item>
    <Item uniqueKey="Folder 2">Folder 2</Item>
    <Item uniqueKey="Folder 3">Folder 3</Item>
    <Item uniqueKey="Folder 4">Folder 4</Item>
    <Item uniqueKey="Folder 5">Folder 5</Item>
  </Breadcrumbs>
</View>

Disabled#

Breadcrumbs in a disabled state shows that selection exists, but is not available in that circumstance. This can be used to maintain layout continuity.

<Breadcrumbs isDisabled>
  <Item uniqueKey="Folder 1">Folder 1</Item>
  <Item uniqueKey="Folder 2">Folder 2</Item>
  <Item uniqueKey="Folder 3">Folder 3</Item>
</Breadcrumbs>