Breadcrumbs

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


Installation

npx nextui-cli@latest add breadcrumbs
The above command is for individual installation only. You may skip this step 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.

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

AttributeTypeDescriptionDefault
children*ReactNodeThe contents of the Breadcrumbs. Usually a list of BreadcrumbItem components.-
variantsolid | bordered | lightThe Breadcrumbs list appearance style.solid
colorforeground | primary | secondary | success | warning | dangerThe Breadcrumbs' items color theme.foreground
sizesm | md | lgThe Breadcrumbs' items size.md
radiusnone | sm | md | lg | fullThe Breadcrumbs list border radius.-
underlinenone | active | hover | focus | alwaysThe Breadcrumbs' items underline style.none
separatorReactNodeThe custom separator between Breadcrumbs. It is a chevron by default.-
maxItemsnumberThe maximum number of breadcrumbs to display.-
itemsBeforeCollapsenumberThe number of items to show before the ellipsis.-
itemsAfterCollapsenumberThe number of items to show after the ellipsis.-
hideSeparatorbooleanWhether to hide the separator between breadcrumbs.false
isDisabledbooleanWhether the Breadcrumbs are disabled except the last item.false
disableAnimationbooleanWhether the Breadcrumbs should display animations.false
itemClassesRecord<"base"| "item"| "separator", string>Allows to set custom class names for the breadcrumbs item slots.-
classNamesRecord<"base"| "list"| "ellipsis"| "separator", string>Allows to set custom class names for the breadcrumbs slots.-
AttributeTypeDescription
renderEllipsisRenderEllipsisFunctionHandler called when the press is released over the target.
AttributeTypeDescription
onAction(key: React.Key) => voidHandler called when any breadcrumb item is pressed. It returns the item key.
AttributeTypeDescriptionDefault
children*ReactNodeThe contents of the item. Usually the link label or icon.-
colorforeground | primary | secondary | success | warning | dangerThe item color theme.foreground
sizesm | md | lgThe item size.md
underlinenone | active | hover | focus | alwaysThe item underline style.none
startContentReactNodeThe item start content.-
endContentReactNodeThe item end content.-
separatorReactNodeThe item custom separator. It is a chevron by default.-
isCurrentbooleanWhether the item is the current/active one.false
isLastbooleanWhether the item is the last one.false
hideSeparatorbooleanWhether to hide the item separator.false
isDisabledbooleanWhether the item is disabled.false
disableAnimationbooleanWhether the item should display animations.false
classNamesRecord<"base"| "item"| "separator", string>Allows to set custom class names for the item slots.-
AttributeTypeDescription
onPress(e: PressEvent) => voidHandler called when the press is released over the target.
onPressStart(e: PressEvent) => voidHandler called when a press interaction starts.
onPressEnd(e: PressEvent) => voidHandler called when a press interaction ends, either over the target or when the pointer leaves the target.
onKeyDown(e: KeyboardEvent) => voidHandler called when a key is pressed.
onKeyUp(e: KeyboardEvent) => voidHandler called when a key is released.

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;
};
/**
* 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;