Breadcrumbs

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

install	`yarn add @react-spectrum/breadcrumbs`
version	3.0.0-alpha.1
usage	`import {Breadcrumbs, Item} from '@react-spectrum/breadcrumbs'`

View guidelines

Spectrum

Example#

<Breadcrumbs>
  <Item key="home">Home</Item>
  <Item key="trendy">Trendy</Item>
  <Item key="march 2020 assets">March 2020 Assets</Item>
</Breadcrumbs>

<Breadcrumbs>
  <Item key="home">Home</Item>
  <Item key="trendy">Trendy</Item>
  <Item key="march 2020 assets">March 2020 Assets</Item>
</Breadcrumbs>

<Breadcrumbs>
  <Item key="home">
    Home
  </Item>
  <Item key="trendy">
    Trendy
  </Item>
  <Item key="march 2020 assets">
    March 2020 Assets
  </Item>
</Breadcrumbs>

Content#

Breadcrumbs follow the Collection Components API, accepting only static children. Similar to the Menu, Breadcrumbs accept an <Item> component, each with a key prop which is passed to the onAction handler to identify the selected item. Basic usage of Breadcrumbs, seen in the example above, shows a list of Item components, populated with a string. See Events for more information.

Internationalization#

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

To use Breadcrumbs as a heading, render a Heading component inside your Item. You may set the heading level by providing the level prop.

import {Heading} from '@react-spectrum/text';

<Breadcrumbs>
  <Item key="home">
    Home
  </Item>
  <Item key="trendy">
    Trendy
  </Item>
  <Item key="march 2020 assets">
    <Heading level={2}>
      March 2020 Assets
    </Heading>
  </Item>
</Breadcrumbs>

import {Heading} from '@react-spectrum/text';

<Breadcrumbs>
  <Item key="home">
    Home
  </Item>
  <Item key="trendy">
    Trendy
  </Item>
  <Item key="march 2020 assets">
    <Heading level={2}>
      March 2020 Assets
    </Heading>
  </Item>
</Breadcrumbs>

import {Heading} from '@react-spectrum/text';

<Breadcrumbs>
  <Item key="home">
    Home
  </Item>
  <Item key="trendy">
    Trendy
  </Item>
  <Item key="march 2020 assets">
    <Heading level={2}>
      March 2020 Assets
    </Heading>
  </Item>
</Breadcrumbs>

Events#

Use the onAction prop as a callback to handle press events on items.

function Example() {
  let folders = [
    {id: 1, label: 'Home'},
    {id: 2, label: 'Trendy'},
    {id: 3, label: 'March 2020 Assets'}
  ];
  let [folderId, setFolderId] = React.useState();
  return (
    <div>
      <Breadcrumbs onAction={(a) => setFolderId(a)}>
        {folders.map(f => <Item key={f.id}>{f.label}</Item>)}
      </Breadcrumbs>
      <p>You pressed folder ID: {folderId}</p>
    </div>
  );
}

function Example() {
  let folders = [
    {id: 1, label: 'Home'},
    {id: 2, label: 'Trendy'},
    {id: 3, label: 'March 2020 Assets'}
  ];
  let [folderId, setFolderId] = React.useState();
  return (
    <div>
      <Breadcrumbs onAction={(a) => setFolderId(a)}>
        {folders.map((f) => (
          <Item key={f.id}>{f.label}</Item>
        ))}
      </Breadcrumbs>
      <p>You pressed folder ID: {folderId}</p>
    </div>
  );
}

function Example() {
  let folders = [
    {
      id: 1,
      label: 'Home'
    },
    {
      id: 2,
      label: 'Trendy'
    },
    {
      id: 3,
      label:
        'March 2020 Assets'
    }
  ];
  let [
    folderId,
    setFolderId
  ] = React.useState();
  return (
    <div>
      <Breadcrumbs
        onAction={(a) =>
          setFolderId(a)
        }>
        {folders.map(
          (f) => (
            <Item
              key={f.id}>
              {f.label}
            </Item>
          )
        )}
      </Breadcrumbs>
      <p>
        You pressed
        folder ID:{' '}
        {folderId}
      </p>
    </div>
  );
}

Props#

Name	Type	Default	Description
`size`	`'S' \| 'M' \| 'L'`	`'L'`	Size of the Breadcrumbs including spacing and layout.
`maxVisibleItems`	`'auto' \| number`	`4`	The current number of visible items before items are collapsed.
`showRoot`	`boolean`	—	Whether to always show the root item if the items are collapsed.
`isMultiline`	`boolean`	—	Whether to place the last Breadcrumb item onto a new line.
`children`	`ReactElement<ItemProps<T>> \| ReactElement<ItemProps<T>>[]`	—	The breadcrumb items.
`isDisabled`	`boolean`	—	Whether the Breadcrumbs are disabled.

Events

Name	Type	Default	Description
`onAction`	`( (key: Key )) => void`	—	Called when an item is acted upon (usually selection via press).

Layout

Name	Type	Default	Description
`flex`	`string \| number \| boolean`	—	When used in a flex layout, specifies how the element will grow or shrink to fit the space available. See MDN.
`flexGrow`	`number`	—	When used in a flex layout, specifies how the element will grow to fit the space available. See MDN.
`flexShrink`	`number`	—	When used in a flex layout, specifies how the element will shrink to fit the space available. See MDN.
`flexBasis`	`number \| string`	—	When used in a flex layout, specifies the initial main size of the element. See MDN.
`alignSelf`	`'auto' \| 'normal' \| 'start' \| 'end' \| 'center' \| 'flex-start' \| 'flex-end' \| 'self-start' \| 'self-end' \| 'stretch'`	—	Overrides the `alignItems` property of a flex or grid container. See MDN.
`justifySelf`	`'auto' \| 'normal' \| 'start' \| 'end' \| 'flex-start' \| 'flex-end' \| 'self-start' \| 'self-end' \| 'center' \| 'left' \| 'right' \| 'stretch'`	—	Specifies how the element is justified inside a flex or grid container. See MDN.
`order`	`number`	—	The layout order for the element within a flex or grid container. See MDN.
`gridArea`	`string`	—	When used in a grid layout, specifies the named grid area that the element should be placed in within the grid. See MDN.
`gridColumn`	`string`	—	When used in a grid layout, specifies the column the element should be placed in within the grid. See MDN.
`gridRow`	`string`	—	When used in a grid layout, specifies the row the element should be placed in within the grid. See MDN.
`gridColumnStart`	`string`	—	When used in a grid layout, specifies the starting column to span within the grid. See MDN.
`gridColumnEnd`	`string`	—	When used in a grid layout, specifies the ending column to span within the grid. See MDN.
`gridRowStart`	`string`	—	When used in a grid layout, specifies the starting row to span within the grid. See MDN.
`gridRowEnd`	`string`	—	When used in a grid layout, specifies the ending row to span within the grid. See MDN.

Spacing

Name	Type	Default	Description
`margin`	`DimensionValue`	—	The margin for all four sides of the element. See MDN.
`marginTop`	`DimensionValue`	—	The margin for the top side of the element. See MDN.
`marginBottom`	`DimensionValue`	—	The margin for the bottom side of the element. See MDN.
`marginStart`	`DimensionValue`	—	The margin for the logical start side of the element, depending on layout direction. See MDN.
`marginEnd`	`DimensionValue`	—	The margin for the logical end side of an element, depending on layout direction. See MDN.
`marginX`	`DimensionValue`	—	The margin for both the left and right sides of the element. See MDN.
`marginY`	`DimensionValue`	—	The margin for both the top and bottom sides of the element. See MDN.

Sizing

Name	Type	Default	Description
`width`	`DimensionValue`	—	The width of the element. See MDN.
`minWidth`	`DimensionValue`	—	The minimum width of the element. See MDN.
`maxWidth`	`DimensionValue`	—	The maximum width of the element. See MDN.
`height`	`DimensionValue`	—	The height of the element. See MDN.
`minHeight`	`DimensionValue`	—	The minimum height of the element. See MDN.
`maxHeight`	`DimensionValue`	—	The maximum height of the element. See MDN.

Positioning

Name	Type	Default	Description
`position`	`'static' \| 'relative' \| 'absolute' \| 'fixed' \| 'sticky'`	—	Specifies how the element is positioned. See MDN.
`top`	`DimensionValue`	—	The top position for the element. See MDN.
`bottom`	`DimensionValue`	—	The bottom position for the element. See MDN.
`left`	`DimensionValue`	—	The left position for the element. See MDN. Consider using `start` instead for RTL support.
`right`	`DimensionValue`	—	The right position for the element. See MDN. Consider using `start` instead for RTL support.
`start`	`DimensionValue`	—	The logical start position for the element, depending on layout direction. See MDN.
`end`	`DimensionValue`	—	The logical end position for the element, depending on layout direction. See MDN.
`zIndex`	`number`	—	The stacking order for the element. See MDN.
`isHidden`	`boolean`	—	Hides the element.

Accessibility

Name	Type	Default	Description
`id`	`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-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.

Advanced

Name	Type	Default	Description
`UNSAFE_className`	`string`	—	Sets the CSS className for the element. Only use as a last resort. Use style props instead.
`UNSAFE_style`	`CSSProperties`	—	Sets inline style for the element. Only use as a last resort. Use style props instead.

Visual options#

Size#

View guidelines

Small

<Breadcrumbs size="S">
  <Item key="home">Home</Item>
  <Item key="trendy">Trendy</Item>
</Breadcrumbs>

<Breadcrumbs size="S">
  <Item key="home">Home</Item>
  <Item key="trendy">Trendy</Item>
</Breadcrumbs>

<Breadcrumbs size="S">
  <Item key="home">
    Home
  </Item>
  <Item key="trendy">
    Trendy
  </Item>
</Breadcrumbs>

Medium

<Breadcrumbs size="M">
  <Item key="home">Home</Item>
  <Item key="trendy">Trendy</Item>
</Breadcrumbs>

<Breadcrumbs size="M">
  <Item key="home">Home</Item>
  <Item key="trendy">Trendy</Item>
</Breadcrumbs>

<Breadcrumbs size="M">
  <Item key="home">
    Home
  </Item>
  <Item key="trendy">
    Trendy
  </Item>
</Breadcrumbs>

Large (default)

<Breadcrumbs size="L">
  <Item key="home">Home</Item>
  <Item key="trendy">Trendy</Item>
</Breadcrumbs>

<Breadcrumbs size="L">
  <Item key="home">Home</Item>
  <Item key="trendy">Trendy</Item>
</Breadcrumbs>

<Breadcrumbs size="L">
  <Item key="home">
    Home
  </Item>
  <Item key="trendy">
    Trendy
  </Item>
</Breadcrumbs>

Multiline#

Use the isMultiline prop to place the selected item below the other items. This adds emphasis to the selected item as a page title or heading.

<Breadcrumbs isMultiline>
  <Item key="home">Home</Item>
  <Item key="trendy">Trendy</Item>
  <Item key="march 2020 assets">March 2020 Assets</Item>
</Breadcrumbs>

<Breadcrumbs isMultiline>
  <Item key="home">Home</Item>
  <Item key="trendy">Trendy</Item>
  <Item key="march 2020 assets">March 2020 Assets</Item>
</Breadcrumbs>

<Breadcrumbs
  isMultiline>
  <Item key="home">
    Home
  </Item>
  <Item key="trendy">
    Trendy
  </Item>
  <Item key="march 2020 assets">
    March 2020 Assets
  </Item>
</Breadcrumbs>

Visible items (overflow behavior)#

View guidelines

Breadcrumbs collapse into a menu by default, showing only a maximum of visible 4 items.

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

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

<Breadcrumbs maxVisibleItems={2}>
  <Item key="home">Home</Item>
  <Item key="trendy">Trendy</Item>
  <Item key="march 2020 assets">March 2020 Assets</Item>
</Breadcrumbs>

<Breadcrumbs maxVisibleItems={2}>
  <Item key="home">Home</Item>
  <Item key="trendy">Trendy</Item>
  <Item key="march 2020 assets">March 2020 Assets</Item>
</Breadcrumbs>

<Breadcrumbs
  maxVisibleItems={2}>
  <Item key="home">
    Home
  </Item>
  <Item key="trendy">
    Trendy
  </Item>
  <Item key="march 2020 assets">
    March 2020 Assets
  </Item>
</Breadcrumbs>

Root context#

View guidelines

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 key="home">Home</Item>
    <Item key="trendy">Trendy</Item>
    <Item key="2020 assets">March 2020 Assets</Item>
    <Item key="winter">Winter</Item>
    <Item key="holiday">Holiday</Item>
  </Breadcrumbs>
</View>

<View overflow="hidden" width="200px">
  <Breadcrumbs showRoot maxVisibleItems="auto">
    <Item key="home">Home</Item>
    <Item key="trendy">Trendy</Item>
    <Item key="2020 assets">March 2020 Assets</Item>
    <Item key="winter">Winter</Item>
    <Item key="holiday">Holiday</Item>
  </Breadcrumbs>
</View>

<View
  overflow="hidden"
  width="200px">
  <Breadcrumbs
    showRoot
    maxVisibleItems="auto">
    <Item key="home">
      Home
    </Item>
    <Item key="trendy">
      Trendy
    </Item>
    <Item key="2020 assets">
      March 2020 Assets
    </Item>
    <Item key="winter">
      Winter
    </Item>
    <Item key="holiday">
      Holiday
    </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 key="home">Home</Item>
  <Item key="trendy">Trendy</Item>
  <Item key="march 2020 assets">March 2020 Assets</Item>
</Breadcrumbs>

<Breadcrumbs isDisabled>
  <Item key="home">Home</Item>
  <Item key="trendy">Trendy</Item>
  <Item key="march 2020 assets">March 2020 Assets</Item>
</Breadcrumbs>

<Breadcrumbs
  isDisabled>
  <Item key="home">
    Home
  </Item>
  <Item key="trendy">
    Trendy
  </Item>
  <Item key="march 2020 assets">
    March 2020 Assets
  </Item>
</Breadcrumbs>

Item<T>(
  (props: ItemProps<T>
)): ReactElement

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.

See the Styling docs for a visualization of these values.

'size-0'
  | 'size-10'
  | 'size-25'
  | 'size-40'
  | 'size-50'
  | 'size-65'
  | 'size-75'
  | 'size-85'
  | 'size-100'
  | 'size-115'
  | 'size-125'
  | 'size-130'
  | 'size-150'
  | 'size-160'
  | 'size-175'
  | 'size-200'
  | 'size-225'
  | 'size-250'
  | 'size-300'
  | 'size-350'
  | 'size-400'
  | 'size-450'
  | 'size-500'
  | 'size-550'
  | 'size-600'
  | 'size-675'
  | 'size-700'
  | 'size-800'
  | 'size-900'
  | 'size-1000'
  | 'size-1200'
  | 'size-1250'
  | 'size-1600'
  | 'size-1700'
  | 'size-2000'
  | 'size-2400'
  | 'size-3000'
  | 'size-3400'
  | 'size-3600'
  | 'size-4600'
  | 'size-5000'
  | 'size-6000'
  | 'static-size-0'
  | 'static-size-10'
  | 'static-size-25'
  | 'static-size-50'
  | 'static-size-40'
  | 'static-size-65'
  | 'static-size-100'
  | 'static-size-115'
  | 'static-size-125'
  | 'static-size-150'
  | 'static-size-175'
  | 'static-size-200'
  | 'static-size-225'
  | 'static-size-250'
  | 'static-size-300'
  | 'static-size-400'
  | 'static-size-450'
  | 'static-size-500'
  | 'static-size-550'
  | 'static-size-600'
  | 'static-size-700'
  | 'static-size-800'
  | 'static-size-900'
  | 'static-size-1000'
  | 'static-size-1200'
  | 'static-size-1700'
  | 'static-size-2400'
  | 'static-size-2600'
  | 'static-size-3400'
  | 'static-size-3600'
  | 'static-size-4600'
  | 'static-size-5000'
  | 'static-size-6000'
  | 'single-line-height'
  | 'single-line-width'
  | string & {}
  | number

Breadcrumbs

Example#

Content#

Internationalization#

Breadcrumb as heading#

Events#

Props#

Visual options#

Size#

Multiline#

Visible items (overflow behavior)#

Root context#

Disabled#