Breadcrumbs display a hierarchy of links to the current page or resource in an application.
Storybook@nextui-org/breadcrumbsSourceStyles sourceInstallationnpx nextui-cli@latest add breadcrumbsThe above command is for individual installation only. You may skip this step if @nextui-org/react is already installed globally.ImportNextUI 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.UsageDisabledDisabled breadcrumbs display items but prevent navigation, ensuring a consistent layout. The last item, signifying the current page, isn't disabled.
SizesColorsVariantsUnderlinesRadiusRoutingThe component works with frameworks and client side routers like Next.js andReact Router. See the Routing guide to learn how to set this up.
ControlledYou 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 TypeIt is possible to use the Breadcrumbs component as a horizontal menu. This is useful when you want to display a listof possible navigations and let the user choose one of them.
Start & End ContentYou can add any element to the start or end of the breadcrumbs by using the startContent and endContent props. Theabove example uses the startContent prop to add icons to the start of the breadcrumbs.
Custom SeparatorYou can customize the separator between breadcrumbs by using the separator prop.
Custom Itemsthe BreadcrumbItem component accepts any element as its children. This allows you to customize the appearance of thebreadcrumb 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 cannotplace any other component directly inside the Breadcrumbs component.
// ❌ This will not work,// The Button will not be picked by the Breadcrumbs component. Item 1 Item 2// ✅ Instead, you can wrap the Button inside a BreadcrumbItem. Item 1 Item 2 Collapsing ItemsThe Breadcrumb component provides 3 props to control the collapsing of items:
maxItems: Specifies the maximum number of breadcrumbs to display. When there are morethan the maximum number, only the first itemsBeforeCollapse and last itemsAfterCollapsewill 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 ItemYou can customize the ellipsis item by using the renderEllipsis prop. This prop accepts a function that returns aReact element.
SlotsBreadcrumbs 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 StylesYou can customize the Breadcrumbs style by using the classNames prop and its items by using the itemClasses prop.
Data AttributesBreadcrumbItem 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.AccessibilityImplemented as an ordered list of items.Support for mouse, touch, and keyboard interactions on breadcrumbs.Support for navigation links via 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.APIBreadcrumbs PropsAttributeTypeDescriptionDefaultchildren*ReactNodeThe contents of the Breadcrumbs. Usually a list of BreadcrumbItem components.-variantsolid | bordered | lightThe Breadcrumbs list appearance style.solidcolorforeground | primary | secondary | success | warning | dangerThe Breadcrumbs' items color theme.foregroundsizesm | md | lgThe Breadcrumbs' items size.mdradiusnone | sm | md | lg | fullThe Breadcrumbs list border radius.-underlinenone | active | hover | focus | alwaysThe Breadcrumbs' items underline style.noneseparatorReactNodeThe 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.falseisDisabledbooleanWhether the Breadcrumbs are disabled except the last item.falsedisableAnimationbooleanWhether the Breadcrumbs should display animations.falseitemClassesRecordAllows to set custom class names for the breadcrumbs item slots.-classNamesRecordAllows to set custom class names for the breadcrumbs slots.-Breadcrumbs FunctionsAttributeTypeDescriptionrenderEllipsisRenderEllipsisFunctionHandler called when the press is released over the target.Breadcrumbs EventsAttributeTypeDescriptiononAction(key: React.Key) => voidHandler called when any breadcrumb item is pressed. It returns the item key.BreadcrumbItem PropsAttributeTypeDescriptionDefaultchildren*ReactNodeThe contents of the item. Usually the link label or icon.-colorforeground | primary | secondary | success | warning | dangerThe item color theme.foregroundsizesm | md | lgThe item size.mdunderlinenone | active | hover | focus | alwaysThe item underline style.nonestartContentReactNodeThe 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.falseisLastbooleanWhether the item is the last one.falsehideSeparatorbooleanWhether to hide the item separator.falseisDisabledbooleanWhether the item is disabled.falsedisableAnimationbooleanWhether the item should display animations.falseclassNamesRecordAllows to set custom class names for the item slots.-BreadcrumbItem EventsAttributeTypeDescriptiononPress(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.TypesRender Ellipsis Functionexport 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;