Migrating from ghl-ui Avatar to HighRise Avatar

This guide helps migrate ghl-ui UIAvatar to HighRise HLAvatar. HighRise standardizes sizes, adds automatic initials/fallback handling, and keeps a simpler prop surface.

Component Implementation Changes

Import Changes

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

Basic Usage Changes

- <UIAvatar src="/user.jpg" size="medium" />
+ <HLAvatar src="/user.jpg" size="md" />

Props Changes

Core Props

| ghl-ui Prop | HighRise Prop | Notes | | --------------------------- | -------------------------- | ---------------------------------------------------- | ---- | ---- | ---- | ---- | ---- | ----- | ---------------- | | size (default medium) | size (default 'xs') | HighRise uses '2xl' | 'xl' | 'lg' | 'md' | 'sm' | 'xs' | '2xs' | '3xs' or number | | objectFit | objectFit | Same values; default fill | | round | round | Default true in both | | src | src | Same meaning | | style | - | Use preferredInitialsBgColor or global CSS instead | | fallbackSrc | - | HighRise derives initials or uses slot/icon fallback | | indicator/indicatorSize | - | Not supported; provide composed badge externally | | imgProps (optional) | imgProps (default {}) | HighRise merges aria-label with name | | name | name | Optional; used to derive initials and fallback color | | - | preferredInitialsBgColor | Override generated background color | | id | id | Optional but recommended for testing |

Size Mapping

ghl-ui Size	HighRise Size
large	xl
medium	lg
small	md
(none)	xs (default)
numeric	numeric

Event Changes

ghl-ui Event	HighRise Event	Notes
-	@error	Fires when image fails to load
-	@click	Click handler on avatar
@load	-	Not emitted; handle via native events if needed

Slots Changes

ghl-ui Slot	HighRise Slot	Notes
default	default	For initials/icons/custom content
overlay	-	Compose overlays externally (e.g., badge + avatar)

Examples

Basic Image Avatar

<template>
  <HLAvatar id="image-avatar" src="/user.jpg" size="md" @error="handleError" />
</template>

<script setup lang="ts">
const handleError = () => {
  console.warn('Avatar image failed to load')
}
</script>

Initials with Custom Background

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

Square Avatar with Object Fit

<template>
  <HLAvatar id="square-avatar" src="/user.jpg" :round="false" size="xl" object-fit="cover" />
</template>

Icon/Slot Content

<template>
  <HLAvatar id="icon-avatar" size="sm">
    <User01Icon class="w-4 h-4" />
  </HLAvatar>
</template>

Breaking Changes

1. No overlay/indicator props — compose overlays (badges, status) outside the avatar.
2. Fallback behavior — HighRise derives initials and background color from name; fallbackSrc removed.
3. Size tokens — use HighRise size set (lg/md/sm/xs/2xs/3xs/2xl/xl) or numbers; default is xs.
4. Title/content slots removed — only default slot remains; use name for initials.
5. Events added — HighRise emits error and click; listen as needed.

Best Practices

1. Provide name so initials and fallback color stay predictable.
2. Keep size to the standardized tokens; prefer numbers only when necessary.
3. Use preferredInitialsBgColor sparingly; rely on generated colors for consistency.
4. If you need status dots or overlays, wrap HLAvatar with badge/stacked layout.
5. Add id where you need deterministic testing hooks.

MCPs: keep size within the HighRise tokens; avoid overlay/indicator props—compose badges externally; supply name for stable initials/backgrounds when src is missing.