Migrating from UIBreadcrumb to HighRise Breadcrumb

This guide helps migrate slot-based UIBreadcrumb/UIBreadcrumbItem to data-driven HLBreadcrumb.

Component Implementation Changes

Import Changes

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

Data vs. Slots

• Old: slot composition with UIBreadcrumbItem children.
• New: pass an array of breadcrumb objects to the breadcrumbs prop; overflow (4+ items) is automatically collapsed into a dropdown.

Props Changes

| ghl-ui Prop | HighRise Prop | Notes | | ----------- | ------------- | --------------------------------------------------------- | ---- | -------------------- | | separator | separator | Same string prop; default '/' | | slot items | breadcrumbs | Required array { label, href?, clickable?, onClick? } | | - | id | Optional; used for testing/aria hooks | | - | home | Show home icon; default true | | - | homeHref | Default '/'; ignored when onHomeClick provided | | - | onHomeClick | Callback (label: string) => void; prevents nav when set | | - | size | 'lg' | 'md' | 'sm'(default'lg') |

Slots Changes

ghl-ui Slot	HighRise Alternative	Notes
default	-	Use breadcrumbs prop instead
Item slots	-	Items are rendered from data; no per-item slot

Examples

Basic Usage

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

Custom Separator and Non-clickable Last Item

- <UIBreadcrumb separator=">">
-   <UIBreadcrumbItem href="/">Home</UIBreadcrumbItem>
-   <UIBreadcrumbItem href="/products">Products</UIBreadcrumbItem>
-   <UIBreadcrumbItem :clickable="false">Current</UIBreadcrumbItem>
- </UIBreadcrumb>
+ <HLBreadcrumb
+   separator=">"
+   :breadcrumbs="[
+     { label: 'Home', href: '/' },
+     { label: 'Products', href: '/products' },
+     { label: 'Current', clickable: false },
+   ]"
+ />

Disable Home Icon

<template>
  <HLBreadcrumb :home="false" :breadcrumbs="[{ label: 'Section' }, { label: 'Page' }]" />
</template>

Handle Home Click Without Navigation

<template>
  <HLBreadcrumb :breadcrumbs="[{ label: 'Home', href: '/' }, { label: 'Docs' }]" :onHomeClick="label => console.log(label)" />
</template>

Breaking Changes

1. Data-driven only — breadcrumb items are provided via the breadcrumbs prop; item slots/components are removed.
2. Built-in overflow — 4+ items collapse into a dropdown; no manual ellipsis handling needed.
3. Home handling — home/homeHref/onHomeClick control the leading icon/link; default is enabled.
4. Size tokens — limited to lg | md | sm (default lg).

Best Practices

1. Keep breadcrumbs ordered and concise; mark the last item clickable: false when it represents the current page.
2. Supply onHomeClick when you need to prevent navigation or track analytics.
3. Use size="sm" for dense toolbars, md for standard headers, lg for page headers.
4. Let the built-in overflow handle long paths; avoid manually truncating labels.

MCPs: populate breadcrumbs data instead of slots; if you need custom click handling, use onHomeClick or per-item onClick and keep labels short for overflow menus.