Breadcrumbs

Breadcrumbs display a hierarchy of links to the current page or resource in an application.

Installation

nextui add breadcrumbs

No need to install this package if @nextui-org/react is already installed globally.

Import

NextUI exports 2 breadcrumb-related components:

• Breadcumbs: The main component, which is a wrapper for the other components.
• BreadcrumbItem: The component that represents a breadcrumb item.

Usage

Disabled

Disabled breadcrumbs display items but prevent navigation, ensuring a consistent layout. The last item, signifying the current page, isn't disabled.

Sizes

Colors

Variants

Underlines

Radius

Routing

The <BreadcrumbItem> component works with frameworks and client side routers like Next.js and React Router. See the Routing guide to learn how to set this up.

Controlled

You can control the current/active item by using the isCurrent and onAction props.

Note: If needed you can use the onPress prop to handle the click event on the breadcrumb item.

Menu Type

It is possible to use the Breadcrumbs component as a horizontal menu. This is useful when you want to display a list of possible navigations and let the user choose one of them.

Start & End Content

You can add any element to the start or end of the breadcrumbs by using the startContent and endContent props. The above example uses the startContent prop to add icons to the start of the breadcrumbs.

Custom Separator

You can customize the separator between breadcrumbs by using the separator prop.

Custom Items

the BreadcrumbItem component accepts any element as its children. This allows you to customize the appearance of the breadcrumb items.

The above example uses the Dropdown component to create a dropdown menu in the breadcrumb.

The Breadcrumbs component picks only the BreadcrumbItem components as its children. This means that you cannot place any other component directly inside the Breadcrumbs component.

// ❌ This will not work,
// The Button will not be picked by the Breadcrumbs component.
<Breadcrumbs>
  <BreadcrumbItem>Item 1</BreadcrumbItem>
  <Button>Item 2</Button>
</Breadcrumbs>

// ✅ Instead, you can wrap the Button inside a BreadcrumbItem.
<Breadcrumbs>
  <BreadcrumbItem>Item 1</BreadcrumbItem>
  <BreadcrumbItem>
    <Button>Item 2</Button>
  </BreadcrumbItem>
</Breadcrumbs>

Collapsing Items

The Breadcrumb component provides 3 props to control the collapsing of items:

• maxItems: Specifies the maximum number of breadcrumbs to display. When there are more than the maximum number, only the first itemsBeforeCollapse and last itemsAfterCollapse will be shown, with an ellipsis in between.
• itemsBeforeCollapse: If max items is exceeded, the number of items to show before the ellipsis.
• itemsAfterCollapse: If max items is exceeded, the number of items to show after the ellipsis.

Note: The ellipsis item will use the first collapsed item as its href prop.

Customizing the Ellipsis Item

You can customize the ellipsis item by using the renderEllipsis prop. This prop accepts a function that returns a React element.

Slots

• Breadcrumbs Slots

• base: The main slot for the breadcrumbs. It wraps the list slot.

• list: The list of breadcrumbs wrapper.

• ellipsis: The slot for the ellipsis item. This is only visible when the breadcrumbs are collapsed.

• separator: The slot for the custom separator, the one that can be set using the separator prop.

• BreadcrumbItem Slots

• base: The main slot for the breadcrumb item. It wraps the item slot.

• item: The breadcrumb item wrapper.

• separator: The slot for the item separator.

Customizing the Breadcrumbs Styles

You can customize the Breadcrumbs style by using the classNames prop and its items by using the itemClasses prop.

Data Attributes

BreadcrumbItem has the following attributes on the item element:

• data-current: When the breadcrumb item is the current item. Based on breadcrumb isCurrent prop or on whether the item is the last one.
• data-disabled: When the breadcrumb item is disabled. Based on breadcrumb isDisabled prop.
• data-focus: When the breadcrumb item is being focused. Based on useFocusRing.
• data-focus-visible: When the breadcrumb item is being focused with the keyboard. Based on useFocusRing.

Accessibility

• Implemented as an ordered list of items.
• Support for mouse, touch, and keyboard interactions on breadcrumbs.
• Support for navigation links via <a> elements or custom element types via ARIA.
• Localized ARIA labeling support for landmark navigation region.
• Support for disabled breadcrumbs.
• The last item is automatically marked as the current page using aria-current.

API

Breadcrumbs Props

Breadcrumbs Functions

Breadcrumbs Events

BreadcrumbItem Props

BreadcrumbItem Events

Types

Render Ellipsis Function

export type RenderEllipsisItemProps = {
  /**
   * The collapsed items.
   */
  items: BreadcrumbItemProps[];
  /**
   * The max number of items.
   */
  maxItems: number;
  /**
   * The picked item to render the ellipsis.
   */
  collapsedItem: ReactNode;
  /**
   * The default ellipsis icon.
   */
  ellipsisIcon: ReactNode;
  /**
   * Number of items to show before the ellipsis.
   */
  itemsBeforeCollapse: number;
  /**
   * Number of items to show after the ellipsis.
   */
  itemsAfterCollapse: number;
  /**
   * The separator between each breadcrumb. It is a chevron by default.
   */
  separator: ReactNode;
};

renderEllipsis: (props: RenderEllipsisItemProps) => ReactNode;