Breadcrumbs

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

installyarn add @react-spectrum/breadcrumbs
version3.0.0-alpha.1
usageimport {Breadcrumbs} from '@react-spectrum/breadcrumbs'
View repository
GitHub
View package
NPM

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#

NameTypeDefaultDescription
size'S' | 'M' | 'L'"M"What the Breadcrumbs's size should be.
maxVisibleItems'auto' | number4The current number of visible items before items are collapsed.
showRootboolean—Whether to always show the root item if the items are collapsed.
childrenReactElement<ItemProps<T>> | ReactElement<ItemProps<T>>[]—The breadcrumb items.
isHeadingboolean—Whether the breadcrumbs are used as a heading element.
headingAriaLevelnumber1Sets the aria-level attribute of the last item, but only if isHeading is true.
isDisabledboolean—Whether the Breadcrumbs are disabled.
UNSAFE_classNamestring—
UNSAFE_styleCSSProperties—
Events
NameTypeDefaultDescription
onAction(key: Key) => void—Called when an item is acted upon (usually selection via press).
Layout
NameTypeDefaultDescription
flexstring | number | boolean—
flexGrownumber—
flexShrinknumber—
flexBasisnumber | string—
alignSelf'auto' | 'normal' | 'start' | 'end' | 'flex-start' | 'flex-end' | 'self-start' | 'self-end' | 'center' | 'stretch'—
justifySelf'auto' | 'normal' | 'start' | 'end' | 'flex-start' | 'flex-end' | 'self-start' | 'self-end' | 'center' | 'left' | 'right' | 'stretch'—
flexOrdernumber—
gridAreastring—
gridColumnstring—
gridRowstring—
gridColumnStartstring—
gridColumnEndstring—
gridRowStartstring—
gridRowEndstring—
Spacing
NameTypeDefaultDescription
marginDimensionValue—
marginTopDimensionValue—
marginLeftDimensionValue—
marginRightDimensionValue—
marginBottomDimensionValue—
marginStartDimensionValue—
marginEndDimensionValue—
marginXDimensionValue—
marginYDimensionValue—
Sizing
NameTypeDefaultDescription
widthDimensionValue—
minWidthDimensionValue—
maxWidthDimensionValue—
heightDimensionValue—
minHeightDimensionValue—
maxHeightDimensionValue—
Positioning
NameTypeDefaultDescription
position'static' | 'relative' | 'absolute' | 'fixed' | 'sticky'—
topDimensionValue—
bottomDimensionValue—
leftDimensionValue—
rightDimensionValue—
startDimensionValue—
endDimensionValue—
zIndexnumber—
isHiddenboolean—
Accessibility
NameTypeDefaultDescription
rolestring—
idstring—
tabIndexnumber—
aria-labelstring—Defines a string value that labels the current element.
aria-labelledbystring—Identifies the element (or elements) that labels the current element.
aria-describedbystring—Identifies the element (or elements) that describes the object.
aria-controlsstring—Identifies the element (or elements) whose contents or presence are controlled by the current element.
aria-ownsstring—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-hiddenboolean | 'false' | 'true'—Indicates that the element is perceivable but disabled, so it is not editable or otherwise operable.

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>