005cf56baf
Some checks failed
No response / noResponse (push) Has been cancelled
CI / Continuous releases (push) Has been cancelled
CI / test-dev (macos-latest) (push) Has been cancelled
CI / test-dev (ubuntu-latest) (push) Has been cancelled
CI / test-dev (windows-latest) (push) Has been cancelled
Maintenance / main (push) Has been cancelled
Scorecards supply-chain security / Scorecards analysis (push) Has been cancelled
CodeQL / Analyze (push) Has been cancelled
122 lines
4.2 KiB
Markdown
122 lines
4.2 KiB
Markdown
---
|
||
productId: joy-ui
|
||
title: React Breadcrumbs component
|
||
components: Breadcrumbs
|
||
githubLabel: 'scope: breadcrumbs'
|
||
---
|
||
|
||
# Breadcrumbs
|
||
|
||
<p class="description">A breadcrumb trail is a navigational tool that helps users keep track of their location within an app.</p>
|
||
|
||
{{"component": "@mui/docs/ComponentLinkHeader"}}
|
||
|
||
## 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.
|
||
|
||
{{"demo": "BreadcrumbsUsage.js", "hideToolbar": true, "bg": "gradient"}}
|
||
|
||
## Basics
|
||
|
||
```jsx
|
||
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](#usage-with-link-and-typography), as shown below:
|
||
|
||
{{"demo": "BasicBreadcrumbs.js"}}
|
||
|
||
## Customization
|
||
|
||
### Sizes
|
||
|
||
The Breadcrumbs component comes in three sizes: `sm`, `md` (default), and `lg`:
|
||
|
||
{{"demo": "BreadcrumbsSizes.js"}}
|
||
|
||
:::info
|
||
To learn how to add custom sizes to the component, check out [Themed components—Extend sizes](/joy-ui/customization/themed-components/#extend-sizes).
|
||
:::
|
||
|
||
### 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:
|
||
|
||
{{"demo": "SeparatorBreadcrumbs.js"}}
|
||
|
||
## Usage with Link and Typography
|
||
|
||
```jsx
|
||
import Link from '@mui/joy/Link';
|
||
```
|
||
|
||
```jsx
|
||
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](/joy-ui/react-link/) and [Typography](/joy-ui/react-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:
|
||
|
||
{{"demo": "BreadcrumbsWithIcon.js"}}
|
||
|
||
## 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.
|
||
|
||
{{"demo": "BreadcrumbsVariables.js", "hideToolbar": true, "bg": "gradient"}}
|
||
|
||
## 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:
|
||
|
||
{{"demo": "CondensedBreadcrumbs.js"}}
|
||
|
||
### Condensed with Menu
|
||
|
||
```jsx
|
||
import Menu from '@mui/joy/Menu';
|
||
```
|
||
|
||
As an alternative to the behavior of the condensed demo above, consider adding a [Menu](/joy-ui/react-menu/) component to display the condensed links in a dropdown list:
|
||
|
||
{{"demo": "BreadcrumbsWithMenu.js"}}
|
||
|
||
## Accessibility
|
||
|
||
Be sure to add an informative `aria-label` description to the Breadcrumbs component.
|
||
|
||
The following features, which follows [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/), 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:
|
||
|
||
```html
|
||
<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>
|
||
```
|