Migrating from ghl-ui AvatarGroup to HighRise AvatarGroup

This guide will help you migrate from the ghl-ui AvatarGroup component to the new HighRise AvatarGroup component. The AvatarGroup component has been completely redesigned with enhanced accessibility, consistent sizing, improved interaction features, and better integration with the HighRise design system.

Component Implementation Changes

Import Changes

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

Basic Usage Changes

Basic Group

- <UIAvatarGroup
-   :options="[
-     { src: '/avatar1.jpg', name: 'John Doe' },
-     { src: '/avatar2.jpg', name: 'Jane Smith' },
-     { src: '/avatar3.jpg', name: 'Bob Johnson' }
-   ]"
-   size="large"
- />
+ <HLAvatarGroup
+   id="basic-group"
+   :options="[
+     {
+       name: 'John Doe',
+       src: '/avatar1.jpg',
+       objectFit: 'cover'
+     },
+     {
+       name: 'Jane Smith',
+       src: '/avatar2.jpg',
+       objectFit: 'cover'
+     }
+   ]"
+   size="md"
+   tooltip
+ />

With Indicators

- <UIAvatarGroup
-   :options="[
-     {
-       src: '/avatar1.jpg',
-       name: 'John Doe',
-       indicator: true
-     }
-   ]"
- />
+ <HLAvatarGroup
+   id="status-group"
+   :options="[
+     {
+       name: 'John Doe',
+       src: '/avatar1.jpg',
+       objectFit: 'cover',
+       color: 'green',
+       type: 'success'
+     }
+   ]"
+   status-indicator
+   size="md"
+ />

With Max Display and Action

- <UIAvatarGroup
-   :options="options"
-   size="medium"
-   :max="3"
-   :disableDropdown="false"
- />
+ <HLAvatarGroup
+   id="max-group"
+   :options="options"
+   size="md"
+   :max="3"
+   stacked
+   tooltip
+   action
+   @on-action="handleAction"
+ >
+   <template #action>
+     <PlusIcon />
+   </template>
+ </HLAvatarGroup>

Props Changes

Removed Props

• vertical - Use stacked prop instead
• defaultClassName - Use CSS variables for styling
• restClassName - Use CSS variables for styling
• maxRestCount - Simplified overflow handling
• maxRestHeight - Simplified overflow handling
• disableDropdown - Removed dropdown functionality
• randomizeColor - Colors are now managed through the design system

New Props

Prop Name	Type	Default	Description
id (required)	string	-	Unique identifier for accessibility
stacked	boolean	false	Whether avatars should overlap
tooltip	boolean	false	Show tooltips with avatar names
statusIndicator	boolean	false	Show status indicators on avatars
action	boolean	false	Show action button at the end

Modified Props

Prop Name	Old Values	New Values	Default	Notes
size	'small', 'medium', 'large'	'md', 'sm', 'xs'	'md'	Standardized sizing system
max	number (default: 5)	number	3	Changed default max display count
options	Complex object with many props	Simplified object	[]	Streamlined options structure

Options Object Changes

type AvatarOption = {
-  src?: string
-  name?: string
-  text?: string
-  icon?: Component
-  className?: string
-  style?: CSSProperties
-  indicator?: boolean
-  fallbackSrc?: string
-  indicatorSize?: number
-  tooltipProps?: object
-  objectFit?: string
+  name: string // Required
+  src?: string
+  objectFit?: 'fill' | 'contain' | 'cover' | 'none' | 'scale-down'
+  type?: 'success' | 'error' | 'info' | 'warning'
+  color?: string
+  offset?: [number, number]
+  size?: string
+  border?: boolean
}

Events Changes

Old Event	New Event	Arguments	Description
@click	@on-action	() => void	Emitted when action button is clicked

Slots Changes

Old Slot	New Slot	Description
-	action	Content for the action button

Examples

Basic Group with Tooltips

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

Stacked Group with Max Display

<template>
  <HLAvatarGroup id="stacked-group" :options="options" size="md" :max="3" stacked tooltip />
</template>

<script setup>
const options = [
  {
    name: 'John Doe',
    src: '/avatar1.jpg',
    objectFit: 'cover',
  },
  {
    name: 'Jane Smith',
    src: '/avatar2.jpg',
    objectFit: 'cover',
  },
  {
    name: 'Bob Johnson',
    src: '/avatar3.jpg',
    objectFit: 'cover',
  },
  {
    name: 'Alice Brown',
    src: '/avatar4.jpg',
    objectFit: 'cover',
  },
]
</script>

With Status Indicators and Action

<template>
  <HLAvatarGroup
    id="status-action-group"
    :options="[
      {
        name: 'John Doe',
        src: '/avatar1.jpg',
        objectFit: 'cover',
        type: 'success',
        color: 'green',
      },
      {
        name: 'Jane Smith',
        src: '/avatar2.jpg',
        objectFit: 'cover',
        type: 'error',
        color: 'red',
      },
    ]"
    size="md"
    status-indicator
    action
    @on-action="handleAction"
  >
    <template #action>
      <PlusIcon />
    </template>
  </HLAvatarGroup>
</template>

<script setup>
const handleAction = () => {
  console.log('Action clicked')
}
</script>

Breaking Changes

1. Required Props

   • The id prop is now required for accessibility
   • The name field in options is now required
   • Must be unique within the page context

2. Size System Changes

   • New standardized size tokens: 'md', 'sm', 'xs'
   • Removed support for custom numeric sizes
   • Default size changed to 'md'

3. Options Structure

   • Simplified options object
   • Removed complex styling options
   • New status indicator system
   • Required name field

4. Event Changes

   • Renamed click to on-action
   • Simplified event payload
   • Action button must be explicitly enabled

5. Styling Changes

   • Removed className props
   • Uses CSS variables for theming
   • New status indicator system
   • Changed stacking behavior

6. Feature Removals

   • Removed dropdown functionality
   • Removed vertical layout
   • Removed custom tooltips
   • Removed random color generation

Best Practices

1. Always provide unique id props
2. Use semantic size tokens based on context
3. Provide name for all avatars
4. Handle action events appropriately
5. Use status indicators meaningfully
6. Consider mobile responsiveness
7. Test with various option counts
8. Follow accessibility guidelines
9. Use appropriate image formats
10. Document component usage