# Breadcrumbs · HeroUI

> Migration guide for Breadcrumbs from HeroUI v2 to v3

- Page: https://jiguang132.com/systems/heroui/docs/migration/breadcrumbs
- Based on: HeroUI documentation (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af

> 
  Refer to the [v3 Breadcrumbs documentation](/systems/heroui/docs/components/breadcrumbs) 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:

```tsx
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`:

```tsx
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


  

#### v2


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

#### v3


    ```tsx
    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


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

#### v3


    ```tsx
    {/* 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

---

Index of all JGuang resources: https://jiguang132.com/llms.txt