Migrating from ghl-ui Avatar to HighRise Avatar

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

Component Implementation Changes

Import Changes

- import { UIAvatar } from '@gohighlevel/ghl-ui'
+ import { HLAvatar } from '@platform-ui/highrise'

Basic Usage Changes

Image Avatar

- <UIAvatar
-   src="path/to/image.jpg"
-   size="medium"
- />
+ <HLAvatar
+   id="user-avatar"
+   src="path/to/image.jpg"
+   @error="handleImageError"
+ />

Rounded Avatar

- <UIAvatar
-   src="path/to/image.jpg"
-   round
- />
+ <HLAvatar
+   id="user-avatar"
+   src="path/to/image.jpg"
+   round
+   @error="handleImageError"
+ />

Avatar with Slot

- <UIAvatar>JD</UIAvatar>
+ <HLAvatar
+   id="initials-avatar"
+ >JD</HLAvatar>

Avatar with Initials

- <UIAvatar>JD</UIAvatar>
+ <HLAvatar
+   id="initials-avatar"
+  :name="JD"
+ />

Icon Avatar

- <UIAvatar>
-   <User01Icon class="w-5 h-5" />
- </UIAvatar>
+ <HLAvatar
+   id="icon-avatar"
+   name="John Smith"
+ >
+   <User01Icon />
+ </HLAvatar>

Props Changes

Removed Props

• fallbackSrc - Use name prop for initials fallback instead
• imgProps - Use standard HTML attributes on the component directly
• style - Use preferredInitialsBgColor for background color customization
• Custom numeric sizes - Use predefined size tokens instead

New Props

Prop Name	Type	Default	Description
id (required)	string	-	Unique identifier for accessibility
name (required)	string	-	Full name to generate initials from (e.g., "John Doe" → "JD")
preferredInitialsBgColor	string	undefined	Custom background color for initials avatar

Modified Props

Prop Name	Old Values	New Values	Default	Notes
size	'extra-large', 'large', etc.	'2xl', 'xl', 'lg', 'md', 'sm', 'xs', '2xs', '3xs'	'xs'	Standardized sizing system
round	boolean	boolean	true	if there is no round prop, it should set to true
objectFit	CSS object-fit values	'fill', 'contain', 'cover', 'none', 'scale-down'	'fill'	Restricted to specific values

INFO

if there is no size prop, it should set to sm in highrise.

Events Changes

Old Event	New Event	Arguments	Description
@error	@error	() => void	Emitted when image fails to load
@load	-	-	Removed - handle in parent if needed
@click	@click	() => void	Emitted when avatar is clicked

Slots Changes

Old Slot	New Slot	Description
default	default	Main content slot (for text, icons, or custom content)
overlay	-	Removed - use parent component for overlay functionality

Examples

Basic Image Avatar

<template>
  <HLAvatar id="image-avatar" src="path/to/image.jpg" size="md" @error="handleImageError" />
</template>

<script setup lang="ts">
const handleImageError = () => {
  console.log('Image failed to load')
}
</script>

Initials Avatar with Custom Background

<template>
  <HLAvatar id="custom-initials-avatar" name="John Doe" size="lg" preferred-initials-bg-color="var(--color-primary-500)" />
</template>

Square Avatar with Object Fit

<template>
  <HLAvatar id="square-image-avatar" name="John Smith" src="path/to/image.jpg" :round="false" size="xl" object-fit="cover" />
</template>

Avatar with Icon

<template>
  <HLAvatar id="icon-avatar" name="John Smith" size="sm">
    <template #default>
      <UserIcon class="w-4 h-4" />
    </template>
  </HLAvatar>
</template>

Size Variants

<template>
  <div class="flex gap-2 items-center">
    <HLAvatar
      v-for="size in ['2xl', 'xl', 'lg', 'md', 'sm', 'xs', '2xs', '3xs']"
      :key="size"
      :id="'avatar-' + size"
      :size="size"
      name="John Doe"
    />
  </div>
</template>

Size Mapping

ghl-ui Size	HighRise Size	Dimensions	Use Case
extra-large	2xl	64px	Hero sections, profile pages
large	xl	56px	Large profile displays
medium	lg	48px	Standard profile views
small	md	40px	List items, navigation
extra-small	sm	32px	Compact lists
-	xs	24px	Dense UIs, default size
-	2xs	20px	Very compact displays
-	3xs	16px	Minimal indicators

Breaking Changes

1. Required Props

   • The id prop is now required for accessibility
   • The name prop is now required for all avatar variants
   • Both must be unique within the page context

2. Size System Changes

   • Removed support for numeric sizes
   • New standardized size tokens
   • Default size changed to 'xs' (24px)

3. Initials Generation

   • Now requires name prop instead of direct text content
   • Automatically generates initials from full name
   • Example: name="John Doe" → displays "JD"

4. Styling Changes

   • Removed direct style prop support
   • Use preferredInitialsBgColor for background customization
   • Uses CSS variables for theming

5. Default Behavior

   • round prop defaults to true (was false)
   • Removed fallbackSrc in favor of initials
   • Removed overlay slot

6. Event Handling

   • Removed @load event
   • Simplified error handling
   • Click event returns no payload

7. DOM Structure

   • Modified internal markup for accessibility
   • Added ARIA attributes
   • Changed class naming convention

Best Practices

1. Always provide a unique id prop for accessibility
2. Use semantic size tokens based on context
3. Provide name prop for automatic initials generation
4. Handle image loading errors appropriately
5. Use CSS variables for theming when possible
6. Follow accessibility guidelines
7. Keep avatar dimensions consistent
8. Use appropriate image formats and sizes
9. Test across different viewports
10. Document component usage

Additional Notes

1. Enhanced accessibility with ARIA attributes
2. Improved performance with optimized rendering
3. Better TypeScript support
4. Consistent theming with design system
5. RTL layout support
6. Automatic color generation for initials
7. Improved error handling
8. Better integration with other HighRise components
9. Standardized sizing system
10. Simplified API surface