Migrating from UIBreadcrumb to HighRise Breadcrumb

This guide will help you migrate from the ghl-ui Breadcrumb component to the new HighRise Breadcrumb component.

Component Implementation Changes

Import Changes

- import { UIBreadcrumb, UIBreadcrumbItem } from '@gohighlevel/ghl-ui'
+ import { HLBreadcrumb } from '@platform-ui/highrise'

Breaking Changes

The new Breadcrumb component uses a data-driven approach instead of slot-based composition:

• Old: Slot-based with individual UIBreadcrumbItem components
• New: Array-based using the breadcrumbs prop with BreadcrumbItem interface

Props Changes

1. New Required Props:

   • id: Required for accessibility
   • breadcrumbs: Array of breadcrumb items

2. New Optional Props:

   • home: Boolean to show/hide home icon (default: true)
   • size: 'sm' | 'md' | 'lg' (default: 'lg')

3. Changed Props:

   • separator: Still optional, but now only accepts string (default: '/')

Slots Changes

The following slots have been removed:

• default slot - Use breadcrumbs prop instead
• Individual UIBreadcrumbItem components are no longer used

Examples

Basic Usage

- <UIBreadcrumb>
-   <UIBreadcrumbItem>Home</UIBreadcrumbItem>
-   <UIBreadcrumbItem>Products</UIBreadcrumbItem>
-   <UIBreadcrumbItem>Laptops</UIBreadcrumbItem>
- </UIBreadcrumb>

+ <HLBreadcrumb
+   id="example-breadcrumb"
+   :breadcrumbs="[
+     { label: 'Home', href: '/' },
+     { label: 'Products', href: '/products' },
+     { label: 'Laptops', href: '/products/laptops' }
+   ]"
+ />

With Custom Separator

- <UIBreadcrumb separator=">">
-   <UIBreadcrumbItem>One</UIBreadcrumbItem>
-   <UIBreadcrumbItem>Two</UIBreadcrumbItem>
-   <UIBreadcrumbItem>Three</UIBreadcrumbItem>
- </UIBreadcrumb>

+ <HLBreadcrumb
+   id="custom-separator-breadcrumb"
+   separator=">"
+   :breadcrumbs="[
+     { label: 'One', href: '/one' },
+     { label: 'Two', href: '/two' },
+     { label: 'Three', href: '/three' }
+   ]"
+ />

With Links and Non-clickable Items

- <UIBreadcrumb>
-   <UIBreadcrumbItem href="/">Home</UIBreadcrumbItem>
-   <UIBreadcrumbItem href="/products">Products</UIBreadcrumbItem>
-   <UIBreadcrumbItem :clickable="false">Current Page</UIBreadcrumbItem>
- </UIBreadcrumb>

+ <HLBreadcrumb
+   id="mixed-breadcrumb"
+   :breadcrumbs="[
+     { label: 'Home', href: '/' },
+     { label: 'Products', href: '/products' },
+     { label: 'Current Page', clickable: false }
+   ]"
+ />

Without Home Icon

- <UIBreadcrumb>
-   <UIBreadcrumbItem>Home</UIBreadcrumbItem>
-   <UIBreadcrumbItem>Products</UIBreadcrumbItem>
- </UIBreadcrumb>

+ <HLBreadcrumb
+   id="no-home-breadcrumb"
+   :home="false"
+   :breadcrumbs="[
+     { label: 'Home', href: '/' },
+     { label: 'Products', href: '/products' }
+   ]"
+ />

With Overflow (4+ items)

<template>
  <HLBreadcrumb id="overflow-breadcrumb" :breadcrumbs="longBreadcrumbs" />
</template>

<script setup>
const longBreadcrumbs = [
  { label: 'Home', href: '/' },
  { label: 'Category', href: '/category' },
  { label: 'Subcategory', href: '/category/sub' },
  { label: 'Products', href: '/category/sub/products' },
  { label: 'Current Item' },
]
</script>

Type Definitions

interface BreadcrumbItem {
  label: string
  href?: string
  clickable?: boolean
}

Best Practices

1. Always provide unique id props for accessibility
2. Use the home prop to control home icon visibility
3. Set appropriate size based on your layout needs
4. Use clickable: false for the current page item
5. Leverage automatic overflow for long breadcrumb paths
6. Keep breadcrumb labels concise and clear
7. Use consistent URL structure in href props
8. Consider mobile responsiveness when setting labels

Additional Notes

1. The component automatically handles overflow for 4+ items
2. Home icon is shown by default but can be disabled
3. The last item is typically styled differently
4. Supports three size variants: 'sm', 'md', 'lg'
5. Uses semantic HTML for better accessibility
6. Maintains consistent spacing and alignment
7. Integrates with the HighRise design system
8. Provides built-in responsive behavior