Migrating from ghl-ui AvatarGroup to HighRise AvatarGroup

UIAvatarGroup maps to HLAvatarGroup, but layout defaults, overflow handling, and status indicators differ. HighRise is horizontal-only, uses smaller size tokens, and status dots appear only when statusIndicator is true and the group is not stacked by default and can be enabled to mimic UIAvatarGroup's look and feel.

Component Implementation Changes

Import Changes

- import { UIAvatarGroup } from '@gohighlevel/ghl-ui'
+ import { HLAvatarGroup } from '@platform-ui/highrise'

Basic Usage Changes

- <UIAvatarGroup :options="options" size="medium" :max="4" />
+ <HLAvatarGroup
+   :options="[
+     { name: 'John Doe', src: '/avatar1.jpg', objectFit: 'cover' },
+     { name: 'Jane Smith', src: '/avatar2.jpg', objectFit: 'cover' },
+   ]"
+   size="md"
+   :max="3"
+   tooltip
+ />

Key Behavioral Differences

• Horizontal only: vertical is removed. Use stacked to overlap avatars; status dots are hidden when stacked.
• Defaults changed: size now defaults to md (ghl-ui default was roughly large); max defaults to 3 (was 5).
• Overflow: anything past max shows in a tooltip with avatars and names. Count is options.length - max; list size/height is not configurable.
• Tooltips: controlled by the tooltip prop and use the avatar name. Per-option tooltipProps are not supported.
• Themes: tooltipTheme controls per-avatar tooltip, overflowTheme controls the overflow list tooltip.
• Colors: HighRise avatars derive background color from text by default; there is no randomizeColor toggle.

Props Changes

ghl-ui Prop	HighRise Prop	Notes
id (required)	id (optional)	Not auto-generated; pass for stable testing/aria hooks.
size (default large)	size	Tokens: md (default), sm, xs, 2xs, 3xs.
max (default 5)	max	Default 3; overflow count is based on options.length - max.
vertical	-	Not supported; horizontal layout only.
options	options	name is required. Removed fields: icon, text, tooltipProps, fallbackSrc, style, indicator. Add imgProps, color/offset for status dots.
defaultClassName/restClassName	-	No per-option class props; style via component class/style or global CSS.
onClose	-	Not emitted.
maxRestCount / maxRestHeight	-	Not configurable; overflow tooltip shows all extras with fixed sizing.
disableDropdown	-	Overflow tooltip cannot be disabled.
randomizeColor	-	Background color comes from initials automatically.
-	stacked	Overlaps avatars horizontally; hides status dots.
-	tooltip	Global hover tooltip using name; default false.
-	tooltipTheme	dark (default) or light for per-avatar tooltip.
-	overflowTheme	light (default) or dark for overflow tooltip.
-	statusIndicator	Wraps avatars in a badge when true and stacked is false; badge color/offset come from each option.
-	action	Shows trailing action button; emits on-action on click.

Options Object

HighRise options combine avatar props plus optional badge props (used only when statusIndicator is true):

type AvatarGroupOption = {
  name: string
  src?: string
  objectFit?: HLAvatarObjectType // defaults to 'fill'
  imgProps?: ImgHTMLAttributes
  // status indicator (badge) props
  color?: HLBadgeColor
  offset?: [number | string, number | string]
  border?: boolean
}

• Items without name are skipped.
• Status dot size is derived from the group size; dots are suppressed when stacked is true.

Events & Slots

• @on-action — fired when the optional action button is clicked.
• action slot — provide the icon/content for the action button when action is true.

Examples

Basic Group with Tooltip

<template>
  <HLAvatarGroup
    :options="[
      { name: 'John Doe', src: '/avatar1.jpg', objectFit: 'cover' },
      { name: 'Jane Smith', src: '/avatar2.jpg', objectFit: 'cover' },
    ]"
    size="md"
    :max="3"
    tooltip
  />
</template>

Non-stacked with Status Indicators and Action

<template>
  <HLAvatarGroup :options="options" :max="4" status-indicator action @on-action="handleAdd">
    <template #action>
      <PlusIcon />
    </template>
  </HLAvatarGroup>
</template>

<script setup lang="ts">
const options = [
  { name: 'John Doe', src: '/a1.png', objectFit: 'cover', color: 'success' },
  { name: 'Jane Smith', src: '/a2.png', objectFit: 'cover', color: 'primary' },
  { name: 'Sam Lee', src: '/a3.png', objectFit: 'cover' },
  { name: 'Priya K', src: '/a4.png', objectFit: 'cover' },
]

const handleAdd = () => {
  // open modal or picker
}
</script>