Breadcrumbs

Refer to the v3 Breadcrumbs documentation for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.

Structure Changes

In v2, Breadcrumbs accepted an items prop or children:

import { Breadcrumbs, BreadcrumbItem } from "@heroui/react";

export default function App() {
  return (
    <Breadcrumbs>
      <BreadcrumbItem href="#">Home</BreadcrumbItem>
      <BreadcrumbItem href="#">Products</BreadcrumbItem>
      <BreadcrumbItem>Current Page</BreadcrumbItem>
    </Breadcrumbs>
  );
}

In v3, Breadcrumbs uses a compound component pattern with Breadcrumbs and BreadcrumbsItem:

import { Breadcrumbs, BreadcrumbsItem } from "@heroui/react";

export default function App() {
  return (
    <Breadcrumbs>
      <BreadcrumbsItem href="#">Home</BreadcrumbsItem>
      <BreadcrumbsItem href="#">Products</BreadcrumbsItem>
      <BreadcrumbsItem>Current Page</BreadcrumbsItem>
    </Breadcrumbs>
  );
}

Key Changes

1. Component Name: `BreadcrumbItem` → `BreadcrumbsItem`

v2: Used BreadcrumbItem (singular)
v3: Uses BreadcrumbsItem (plural)

2. Separator Customization

v2: Separator was customizable via props
v3: Separator is customizable via separator prop on Breadcrumbs root

3. Built-in Link Component

v2: Items could be links or text
v3: Items automatically use the Link component when href is provided

4. Prop Changes

v2 Prop	v3 Location	Notes
`maxItems`	-	Removed (render all items or implement collapse manually)
`itemsBeforeCollapse`, `itemsAfterCollapse`, `renderEllipsis`	-	Removed (collapse/ellipsis removed with maxItems)
`items` (prop pattern)	-	Use children instead
`onAction`	-	Use `onPress` on individual items if needed
`isDisabled`	`isDisabled` on root	Now supported on root - disables all breadcrumb links at once
`classNames`, `itemClasses`	-	Use `className` on Breadcrumbs and BreadcrumbsItem

5. `isDisabled` Prop on Root

v2: isDisabled was not available on the root component v3: isDisabled is supported on the Breadcrumbs root, disabling all breadcrumb links at once

6. Automatic `aria-current="page"` Behavior

v3: The last breadcrumb item (the one without href) automatically receives aria-current="page", indicating the current page to assistive technologies. No manual configuration is needed.

7. React Aria Components Integration

v3: Built on React Aria Components for better accessibility and keyboard navigation support

Migration Examples

Custom Separator

<Breadcrumbs separator="/">
  <BreadcrumbItem href="#">Home</BreadcrumbItem>
  <BreadcrumbItem>Current</BreadcrumbItem>
</Breadcrumbs>

import { Icon } from "@iconify/react";
import { Breadcrumbs, BreadcrumbsItem } from "@heroui/react";

<Breadcrumbs separator={<Icon icon="gravity-ui:caret-right" />}>
  <BreadcrumbsItem href="#">Home</BreadcrumbsItem>
  <BreadcrumbsItem>Current</BreadcrumbsItem>
</Breadcrumbs>

Disabled State

{/* v2 did not support isDisabled on the root */}
<Breadcrumbs>
  <BreadcrumbItem href="#">Home</BreadcrumbItem>
  <BreadcrumbItem>Current</BreadcrumbItem>
</Breadcrumbs>

{/* v3 supports isDisabled on root to disable all links */}
<Breadcrumbs isDisabled>
  <BreadcrumbsItem href="#">Home</BreadcrumbsItem>
  <BreadcrumbsItem>Current</BreadcrumbsItem>
</Breadcrumbs>

Summary

Rename BreadcrumbItem to BreadcrumbsItem
Set separator on the root; it can be a string or a React element (e.g. an icon)
Items use the built-in Link when href is provided
isDisabled now supported on root to disable all breadcrumb links at once
The last item (without href) automatically gets aria-current="page" for accessibility
No maxItems / collapse in v3—show all items or implement yourself; use className instead of classNames / itemClasses
Built on React Aria Components for accessibility

On this page