Breadcrumbs

A breadcrumb trail is a navigational tool that helps users keep track of their location within an app.

Introduction

The Breadcrumbs component consists of a list of links that show the user the hierarchy of a given page in relation to the app's structure. It provides a simple visual aid for better context and ease of navigation between higher- and lower-level pages.

<Breadcrumbs>
  <Link />
  ...
</Breadcrumbs>

Playground

size

separator

Basics

import Breadcrumbs from '@mui/joy/Breadcrumbs';

The Breadcrumbs component acts as a wrapper for navigation links. It's designed to be used with the Link and Typography components, as shown below:

<Breadcrumbs aria-label="breadcrumbs">
  {['Home', 'TV Shows', 'Futurama', 'Characters'].map((item: string) => (
    <Link key={item} color="neutral" href="#basics">
      {item}
    </Link>
  ))}
  <Typography>Dr. Zoidberg</Typography>
</Breadcrumbs>

<Breadcrumbs aria-label="breadcrumbs">
  {['Home', 'TV Shows', 'Futurama', 'Characters'].map((item: string) => (
    <Link key={item} color="neutral" href="#basics">
      {item}
    </Link>
  ))}
  <Typography>Dr. Zoidberg</Typography>
</Breadcrumbs>

Press Enter to start editing

Customization

Sizes

The Breadcrumbs component comes in three sizes: sm, md (default), and lg:

Separators

By default, the Breadcrumbs component inserts a forward slash (/) between each navigation item. Use the separator prop to define a custom separator, which can be a character or a symbol as well as an icon:

<Breadcrumbs separator={<KeyboardArrowLeft />} aria-label="breadcrumbs">
  <Typography>Amy</Typography>
  {['Characters', 'Futurama', 'TV Shows', 'Home'].map((item: string) => (
    <Link key={item} color="neutral" href="#separators">
      {item}
    </Link>
  ))}
</Breadcrumbs>

<Breadcrumbs separator={<KeyboardArrowLeft />} aria-label="breadcrumbs">
  <Typography>Amy</Typography>
  {['Characters', 'Futurama', 'TV Shows', 'Home'].map((item: string) => (
    <Link key={item} color="neutral" href="#separators">
      {item}
    </Link>
  ))}
</Breadcrumbs>

Press Enter to start editing

Usage with Link and Typography

import Link from '@mui/joy/Link';

import Typography from '@mui/joy/Typography';

The Breadcrumbs component doesn't accept common Joy UI style props like variant, color, startDecorator, or endDecorator—but Link and Typography do. As such, most custom styles that affect the content should be applied directly to those components rather than Breadcrumbs.

The demo below shows how to add an icon to the Link with startDecorator and change the color with the color prop:

<Breadcrumbs separator="›" aria-label="breadcrumbs">
  <Link color="primary" href="/">
    <PublicIcon sx={{ mr: 0.5 }} />
    United States
  </Link>
  {['Springfield', 'Simpson'].map((item) => (
    <Link key={item} color="success" href="#usage-with-link-and-typography">
      {item}
    </Link>
  ))}

  <Typography>Homer</Typography>
</Breadcrumbs>

<Breadcrumbs separator="›" aria-label="breadcrumbs">
  <Link color="primary" href="/">
    <PublicIcon sx={{ mr: 0.5 }} />
    United States
  </Link>
  {['Springfield', 'Simpson'].map((item) => (
    <Link key={item} color="success" href="#usage-with-link-and-typography">
      {item}
    </Link>
  ))}

  <Typography>Homer</Typography>
</Breadcrumbs>

Press Enter to start editing

CSS variables playground

Play around with the CSS variables available to the Breadcrumbs component to see how the design changes. You can use these to customize the component with both the sx prop and the theme.

<Breadcrumbs />

CSS variables

--Breadcrumbs-gap

Common examples

Condensed Breadcrumbs

When the page hierarchy is deeply nested, you may want to condense multiple levels into one. The demo below only displays a few previous levels until you click the ellipsis to show the full hierarchy:

import Menu from '@mui/joy/Menu';

As an alternative to the behavior of the condensed demo above, consider adding a Menu component to display the condensed links in a dropdown list:

Accessibility

Be sure to add an informative aria-label description to the Breadcrumbs component.

The following features, which follows WAI-ARIA Authoring Practices, are included to optimize the component's baseline accessibility:

The set of links is structured using an ordered list (<ol>).
Visual separators between links are hidden with aria-hidden to prevent screen readers from announcing them.
A <nav> element with an aria-label identifies the structure as a breadcrumb trail and makes it a navigation landmark so that it's easy to locate with assistive technology.
The link to the current page has aria-current set to page.

Anatomy

The Breadcrumbs component is composed of a root <nav> that wraps around an <ol>, with list items corresponding to the trail of links and their separators:

<nav aria-label="breadcrumbs" class="MuiBreadcrumbs-root">
  <ol class="MuiBreadcrumbs-ol">
    <li class="MuiBreadcrumbs-li">
      <!-- Link or Typography -->
    </li>
    <li aria-hidden="true" class="MuiBreadcrumbs-separator">/</li>
    <li class="MuiBreadcrumbs-li css-1rqbcrs-MuiBreadcrumbs-ol">
      <!-- Link or Typography -->
    </li>
  </ol>
</nav>

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.

<Breadcrumbs />