Skip to content
WunderUI

Breadcrumb

Free

Show where a page sits in a hierarchy, and let people step back up.

npx wunderui-cli add breadcrumb

Playground

Installation

bash
npx wunderui-cli add breadcrumb

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

tsx
import {
  Breadcrumb,
  BreadcrumbEllipsis,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbLoading,
  BreadcrumbPage,
  BreadcrumbRestricted,
  BreadcrumbSeparator,
  BreadcrumbSiblingTrigger,
} from "@/components/ui/breadcrumb"
import type {
  BreadcrumbDensity,
  BreadcrumbVariant,
} from "@/components/ui/breadcrumb"

Then use it:

tsx
import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from "@/components/ui/breadcrumb"

export function Trail() {
  return (
    <Breadcrumb density="default">
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="/projects">Projects</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbPage>Assets</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  )
}

Expected result: You should see one trail: the link Projects, a chevron and the text Assets in a darker color.

When to use

Use Breadcrumb for

  • Nested pages, such as one project's assets or one invoice in a customer account
  • A deep hierarchy of files, folders or documentation where people need to step back up
  • Any page that can be reached from more than one place, so the trail names where it lives

Use something else for

  • Tabs for switching between views of the same page
  • Pagination for moving through the pages of one list
  • Stepper for the steps of a process, in a fixed order
  • Sidebar for the whole tree of an app, always on screen

Density

Rows are 36 px high by default and 28 px in side panels and toolbars.

Separator

A chevron by default. A slash suits paths and file locations.

Content

The first level can be text, a Home icon or a workspace. Levels can carry an icon, and a name longer than 160 px ends in an ellipsis.

Deep trails

Keep the root, the parent and the current page, and hide the levels in between behind an ellipsis. On a narrow screen show only a link to the parent.

Level types

A level is a link, a level the person cannot open, a name still loading, or a link with a switcher for its siblings. The current page is always last.

Keyboard interactions

The trail is a list of links, so the browser provides focus and activation. The ellipsis and the sibling trigger are buttons that open a Popover.

TaborShiftTab
Moves focus to the next or previous link or button in the trail, in the order they are written. The current page is not a stop.
Enter
Follows the focused link, or opens the list of hidden levels or siblings from its button.
Space
Opens the list from the ellipsis or the sibling trigger.
Esc
Closes an open list and returns focus to the button that opened it.

Behavior and motion

What the trail draws itself, and what it leaves to the page.

Landmark and list
Breadcrumb is a nav named breadcrumb around an ordered list. Separators are hidden list items, so a screen reader reads the levels and not the chevrons.
Current page
BreadcrumbPage is a span marked as the current page and disabled. It is not a link and does not react to the pointer.
Layout and density
Without density the trail is a small inline list that wraps. With density it is a 36 px or 28 px row on one line, so a trail longer than its box needs collapsing, truncating or a parent link.
Link states
A link darkens and underlines on hover, fills with the subtle tone while pressed and shows the focus ring directly on the item. In the underline look the underline turns primary on hover.
Collapsed levels
BreadcrumbEllipsis is only the button. It opens whatever you put next to it, such as a Popover with links to the hidden levels in their real order, and shows an open state.
Sibling switcher
BreadcrumbSiblingTrigger is a second button beside the link. The link still navigates; the button opens the list of sibling pages and its chevron turns while the list is open.
Restricted level
BreadcrumbRestricted is focusable, shows a lock and explains itself through its title. It is a disabled link and never navigates.
Loading name
BreadcrumbLoading is a quiet grey block that is a status region with an accessible name. There is no spinner.
Long names
Truncated limits a link or the current page to 160 px, ends the text in an ellipsis and sets the full name as the title.
Narrow screens
The trail does not shorten itself. Below 360 px of width show a single link to the parent page instead.
Motion
Color, underline and fill changes are quick. The chevron of the sibling trigger turns 180 degrees while its list is open.
Reduced motion
With reduced motion on, the sibling chevron turns without a transition. Nothing else in the trail moves.

Anatomy

The parts the component is made of. Each one renders a you can target from CSS.

  • data-slot="breadcrumb"

    The nav landmark named breadcrumb. Variant sets the look (plain, contained or underline), and density (36 px or 28 px rows) switches to the sized layout on one line.

  • data-slot="breadcrumb-list"

    The ordered list of items and separators. Contained draws the border and surface and underline the line below; without density it wraps to a second line when room runs out.

  • data-slot="breadcrumb-item"

    One step of the trail, a list item holding a link or, at the end, the current page.

  • data-slot="breadcrumb-link"Optional

    A level above the current page, a link that can hold an icon before the text. Truncated limits it to 160 px with an ellipsis and the full name as its title.

  • data-slot="breadcrumb-ellipsis"Optional

    A button that stands for hidden middle levels. Use it as the trigger of a Popover that lists them; it shows an open state.

  • data-slot="breadcrumb-page"

    The current page as text, not a link, marked as the current page. It can be truncated like a link.

  • data-slot="breadcrumb-sibling-trigger"Optional

    A separate button beside a link that opens a list of sibling pages. The link still navigates; the chevron turns when the list is open.

  • data-slot="breadcrumb-restricted"Optional

    A level the person cannot open. It stays in the trail with a lock, is focusable and explains itself through its title.

  • data-slot="breadcrumb-loading"Optional

    A quiet placeholder for the current level while its name loads. It is a status region; there is no spinner.

  • data-slot="breadcrumb-separator"

    A list item between two items, hidden from screen readers. It shows a chevron, a slash, or your own icon.

Best practices

  • Do

    End the trail with BreadcrumbPage, not a link. It is marked as the current page, so screen readers announce where the person is.

  • Do

    Put a separator between items yourself; the list does not add them. Each one sits in its own list item and is hidden from assistive technology.

  • Do

    Pass a density to get the sized layout: 36 px rows with hover underline, pressed fill and focus ring. Without it the trail is the small inline list.

  • Do

    Collapse deep trails to the root, the parent and the current page. Put the hidden levels behind an ellipsis that opens a list of links, in their real order.

  • Do

    Keep a restricted level visible with BreadcrumbRestricted instead of removing it, so the trail stays truthful.

  • Do

    Show the trail as one link to the parent page below 360 px of width.

  • Don’t

    Don't link the current page or mark a link as current by hand. BreadcrumbPage already marks the last step and is not clickable.

  • Don’t

    Don't show a spinner while the current name loads. Use BreadcrumbLoading, a quiet placeholder with the right accessible name.

  • Don’t

    Don't use a breadcrumb as the only way to move around. It shows the path to the page, not every page there is.

API reference

Each part renders the element it is named after (nav, ol, li, a, span or button) and takes its native attributes, such as href on a link.

The nav landmark named breadcrumb. Variant sets the look (plain, contained or underline), and density (36 px or 28 px rows) switches to the sized layout on one line.

PropTypeDefaultDescription
variant"plain" | "contained" | "underline" | "border""plain"The look of the trail: text, in a bordered box, with a line below. is the old name of .
density"default" | "compact"—Switches to the sized layout on one line: is a 36 px row with 28 px items, a 28 px row with 24 px items. Without it the trail is the small inline list that wraps.

The ordered list of items and separators. Contained draws the border and surface and underline the line below; without density it wraps to a second line when room runs out.

One step of the trail, a list item holding a link or, at the end, the current page.

A list item between two items, hidden from screen readers. It shows a chevron, a slash, or your own icon.

PropTypeDefaultDescription
type"chevron" | "slash""chevron" or . Pass your own icon as children to replace both.

A button that stands for hidden middle levels. Use it as the trigger of a Popover that lists them; it shows an open state.

The current page as text, not a link, marked as the current page. It can be truncated like a link.

PropTypeDefaultDescription
truncatedboolean—Limits the current page to 160 px, ends a long text in an ellipsis and sets the full text as .

A separate button beside a link that opens a list of sibling pages. The link still navigates; the chevron turns when the list is open.

A level the person cannot open. It stays in the trail with a lock, is focusable and explains itself through its title.

A quiet placeholder for the current level while its name loads. It is a status region; there is no spinner.

PropTypeDefaultDescription
labelstring"Loading"The accessible name of the placeholder, read by screen readers as a status. Name what is loading: .

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("breadcrumb")
Installnpx wunderui-cli add breadcrumb

The full library index for assistants is at /llms.txt.