RTL Support: Full

Accessibility: Full

Translations: Not Needed

Migration Guide: Full

Try in Cursor

Avatar

Atomic avatar element that displays either an image, initials, or a fallback icon.

Default

A basic avatar displaying initials passed via the default slot.

CM

<template>
  <HLAvatar id="example-avatar-default">CM</HLAvatar>
</template>

<script setup lang="ts">
  import { HLAvatar } from '@platform-ui/highrise'
</script>

Shape

Avatars are circular by default. Set :round="false" for a square avatar with rounded corners.

CMCM

<template>
  <HLSpace align="center">
    <!-- Round (default) -->
    <HLAvatar size="xl">CM</HLAvatar>
    <!-- Square -->
    <HLAvatar size="xl" :round="false">CM</HLAvatar>

    <HLAvatar
      size="xl"
      src="https://picsum.photos/seed/FeB6P/640/480"
      :imgProps="{ alt: 'old rusted car in an open field in a cloudy background' }"
    />
    <HLAvatar
      size="xl"
      :round="false"
      src="https://picsum.photos/seed/FeB6P/640/480"
      :imgProps="{ alt: 'old rusted car in an open field in a cloudy background' }"
    />
  </HLSpace>
</template>

<script setup lang="ts">
  import { HLAvatar, HLSpace } from '@platform-ui/highrise'
</script>

All Sizes

Use size for the preset scale (2xl–3xs)

CMCMCMCMCMCMCMCM

CMCMCMCMCMCMCMCM

Round

<template>
  <!-- Round Avatars (Default) -->
  <HLSpace align="center">
    <HLAvatar size="2xl">CM</HLAvatar>
    <HLAvatar size="xl">CM</HLAvatar>
    <HLAvatar size="lg">CM</HLAvatar>
    <HLAvatar size="md">CM</HLAvatar>
    <HLAvatar size="sm">CM</HLAvatar>
    <HLAvatar size="xs">CM</HLAvatar>
    <HLAvatar size="2xs">CM</HLAvatar>
    <HLAvatar size="3xs">CM</HLAvatar>
  </HLSpace>
</template>

<script setup lang="ts">
  import { HLAvatar, HLSpace } from '@platform-ui/highrise'
</script>

Square

<template>
  <!-- Square Avatars -->
  <HLSpace align="center">
    <HLAvatar :round="false" size="2xl">CM</HLAvatar>
    <HLAvatar :round="false" size="xl">CM</HLAvatar>
    <HLAvatar :round="false" size="lg">CM</HLAvatar>
    <HLAvatar :round="false" size="md">CM</HLAvatar>
    <HLAvatar :round="false" size="sm">CM</HLAvatar>
    <HLAvatar :round="false" size="xs">CM</HLAvatar>
    <HLAvatar :round="false" size="2xs">CM</HLAvatar>
    <HLAvatar :round="false" size="3xs">CM</HLAvatar>
  </HLSpace>
</template>

<script setup lang="ts">
  import { HLAvatar, HLSpace } from '@platform-ui/highrise'
</script>

Custom Size

Pass a number to size to render the avatar at an exact pixel size.

<template>
  <HLAvatar
    :size="100"
    round
    src="https://picsum.photos/seed/FeB6P/640/480"
    :imgProps="{
      alt: 'old rusted car in an open field in a cloudy background',
    }"
  ></HLAvatar>
</template>

<script setup lang="ts">
  import { HLAvatar } from '@platform-ui/highrise'
</script>

Avatar with Initials

Provide a name and the avatar derives the initials automatically (e.g. "John Doe" → "JD").

JD

AS

RJ

<template>
  <HLSpace align="center">
    <!-- Initials are derived from the name: "John Doe" → "JD" -->
    <HLAvatar id="example-avatar-initials-2xl" size="2xl" name="John Doe" />
    <HLAvatar id="example-avatar-initials-xl" size="xl" name="Alice Smith" />
    <HLAvatar id="example-avatar-initials-lg" size="lg" name="Robert Johnson" />
  </HLSpace>
</template>

<script setup lang="ts">
  import { HLAvatar, HLSpace } from '@platform-ui/highrise'
</script>

Custom Initial Background

When an avatar shows initials, the background color is automatically derived from the name (so the same person always gets the same color). Pass preferredInitialsBgColor to override that with a fixed color — useful when you want avatars to match a brand color or a status palette.

JD

JD

AS

RJ

<template>
  <HLSpace align="center">
    <!-- Auto-generated color derived from the name -->
    <HLAvatar size="lg" name="John Doe" />
    <!-- Fixed background colors (hex, or a CSS variable) -->
    <HLAvatar size="lg" name="John Doe" preferredInitialsBgColor="#26a6a6" />
    <HLAvatar size="lg" name="Alice Smith" preferredInitialsBgColor="#7c3aed" />
    <HLAvatar size="lg" name="Robert Johnson" preferredInitialsBgColor="var(--warning-500)" />
  </HLSpace>
</template>

<script setup lang="ts">
  import { HLAvatar, HLSpace } from '@platform-ui/highrise'
</script>

Custom Initial Color

There is no prop for the initials text color. To control it, render the initials through the default slot instead of the name prop — the slot content replaces the derived initials, so you set both the text and its color yourself. Pair it with preferredInitialsBgColor for a matching background.

JDASRJ

<template>
  <HLSpace align="center">
    <!-- Colour the initials via the default slot; background via preferredInitialsBgColor -->
    <HLAvatar size="lg" preferredInitialsBgColor="var(--primary-50)">
      <span style="color: var(--primary-700)">JD</span>
    </HLAvatar>
    <HLAvatar size="lg" preferredInitialsBgColor="var(--success-100)">
      <span style="color: var(--success-700)">AS</span>
    </HLAvatar>
    <HLAvatar size="lg" preferredInitialsBgColor="var(--warning-100)">
      <span style="color: var(--warning-700)">RJ</span>
    </HLAvatar>
  </HLSpace>
</template>

<script setup lang="ts">
  import { HLAvatar, HLSpace } from '@platform-ui/highrise'
</script>

Avatar with Image

When an image fails to load, the avatar falls back to the initials provided via the name prop.

<template>
  <HLSpace align="center">
    <!-- Avatar with image and event handlers -->
    <HLAvatar
      id="example-avatar-image"
      size="2xl"
      src="https://picsum.photos/seed/FeB6P/640/480"
      :imgProps="{
        alt: 'old rusted car in an open field in a cloudy background',
      }"
      name="John Doe"
      @error="handleImageError"
      @click="handleAvatarClick"
    />

    <!-- Avatar with fallback to initials if image fails -->
    <HLAvatar
      id="example-avatar-fallback"
      size="2xl"
      src="invalid-url.jpg"
      :imgProps="{
        alt: 'alt text for invalid image',
      }"
      name="John Doe"
    />
  </HLSpace>
</template>

<script setup lang="ts">
  import { HLAvatar, HLSpace } from '@platform-ui/highrise'

  const handleImageError = () => console.log('Image failed to load')
  const handleAvatarClick = () => console.log('Avatar clicked')
</script>

Fallback Behavior

When there is no src, the avatar renders the first of these that is available:

1. default slot — any custom content you pass (initials, an icon, an emoji, etc.).
2. Initials from name — derived automatically when the slot is empty.
3. Empty — if neither a slot nor name is provided, the avatar renders as an empty circle. There is no automatic placeholder in this case.

When a src is provided but fails to load, a separate fallback runs: the initials from name if present, otherwise a built-in user icon (User01Icon). This icon appears only on image-load failure — a bare <HLAvatar /> with no src does not show it. The icon is not customizable via a prop; pass a default slot for your own placeholder.

Passing both src and name is safe — and recommended

name doubles as the image-failure fallback: if the image at src fails to load, the avatar falls back to the initials derived from name. You do not need to null out name when src is present. (preferredInitialsBgColor also colors this fallback and the initials background.)

JD

🚀

<template>
  <HLSpace align="center">
    <!-- image + name: shows image, falls back to "JD" if the image fails to load -->
    <HLAvatar size="lg" src="https://picsum.photos/seed/FeB6P/640/480" name="John Doe" />
    <!-- name only: derived initials ("JD") -->
    <HLAvatar size="lg" name="John Doe" />
    <!-- default slot: custom placeholder content -->
    <HLAvatar size="lg">🚀</HLAvatar>
    <!-- src set but broken, no name: the built-in user icon is shown -->
    <HLAvatar size="lg" src="https://invalid-image-url.jpg" />
    <!-- nothing supplied: empty circle (no placeholder) -->
    <HLAvatar size="lg" />
  </HLSpace>
</template>

<script setup lang="ts">
  import { HLAvatar, HLSpace } from '@platform-ui/highrise'
</script>

Image Fit

Use objectFit to control how a non-square image fills the avatar frame. The default fill stretches the image to the frame (which can distort it); cover scales and crops to fill without distortion; contain fits the whole image inside the frame, leaving empty space. This mirrors the CSS object-fit property.

<template>
  <HLSpace align="center">
    <!-- fill (default): stretches to the frame, may distort -->
    <HLAvatar :size="80" objectFit="fill" src="https://picsum.photos/seed/FeB6P/640/480" />
    <!-- cover: scales and crops to fill, no distortion -->
    <HLAvatar :size="80" objectFit="cover" src="https://picsum.photos/seed/FeB6P/640/480" />
    <!-- contain: fits the whole image, may leave empty space -->
    <HLAvatar :size="80" objectFit="contain" src="https://picsum.photos/seed/FeB6P/640/480" />
  </HLSpace>
</template>

<script setup lang="ts">
  import { HLAvatar, HLSpace } from '@platform-ui/highrise'
</script>

Avatar with Status Indicator

To attach a status indicator, place the HLAvatar inside an HLBadge (the avatar is the badge's default slot) and provide the indicator via the badge's #value slot.

Ref: Badge

CM

CM

<template>
  <HLSpace align="center">
    <!-- Status dot indicator -->
    <HLBadge size="2xl" dot :offset="[-10, 60]" id="example-avatar-indicator-2xl">
      <HLAvatar size="2xl">CM</HLAvatar>
      <template #value>
        <div
          style="width: 16px; height: 16px; border-radius: 50%; background: var(--success-500); border: 2px solid #fff"
        ></div>
      </template>
    </HLBadge>

    <!-- Image status indicator -->
   <HLBadge id="example-badge-2" size="sm" dot :offset="[-5, 5]">
      <HLAvatar size="sm" :round="false">CM</HLAvatar>
      <template #value>
        <img src="https://picsum.photos/seed/FeB6P/640/480" alt="status" />
      </template>
    </HLBadge>

  </HLSpace>
</template>
<script setup lang="ts">
  import { HLAvatar, HLBadge, HLSpace } from '@platform-ui/highrise'
</script>

Event Testing

This example shows handling of the @click and @error events. Click on any avatar or try loading an invalid image to see the event log.

AS

Event Log:

No events logged yet. Try clicking the avatars above or loading an invalid image.

<script setup lang="ts">
  import { ref } from 'vue'
  import { HLAvatar, HLSpace } from '@platform-ui/highrise'

  const eventLog = ref([])

  const handleAvatarClick = () => {
    eventLog.value.unshift({ event: 'Avatar clicked', timestamp: new Date().toLocaleTimeString() })
    if (eventLog.value.length > 5) eventLog.value.pop()
  }

  const handleImageError = event => {
    eventLog.value.unshift({
      event: 'Image failed to load',
      details: `Failed URL: ${event.target.src || 'No source URL'}`,
      timestamp: new Date().toLocaleTimeString(),
    })
    if (eventLog.value.length > 5) eventLog.value.pop()
  }
</script>

<template>
  <HLSpace align="center">
    <HLAvatar
      id="example-avatar-events-1"
      size="lg"
      src="https://picsum.photos/seed/FeB6P/640/480"
      @click="handleAvatarClick"
      @error="handleImageError"
    />
    <!-- Invalid src triggers @error -->
    <HLAvatar
      id="example-avatar-events-2"
      size="lg"
      src="https://invalid-image-url.jpg"
      @click="handleAvatarClick"
      @error="handleImageError"
    />
    <HLAvatar id="example-avatar-events-3" size="lg" name="Alice Smith" @click="handleAvatarClick" />
  </HLSpace>
  <div class="text-sm">
    <p class="font-bold mb-2">Event Log:</p>
    <div v-if="eventLog.length === 0" class="text-gray-500">No events logged yet.</div>
    <div v-for="(log, index) in eventLog" :key="index" class="text-gray-700">
      {{ log.timestamp }}: {{ log.event }}
      <div v-if="log.details" class="ml-4 text-gray-500 text-xs">{{ log.details }}</div>
    </div>
  </div>
</template>

Custom Avatar Sizes

Bind a reactive number to size to resize the avatar dynamically at runtime.

Custom size (px)

CMCM

<template>
  <HLAvatar id="example-avatar-default-custom-size" :size="customAvatarSize">CM</HLAvatar>
  <HLAvatar id="example-avatar-default-custom-size-square" :size="customAvatarSize" :round="false">CM</HLAvatar>
</template>

<script setup lang="ts">
  import { ref } from 'vue'
  import { HLAvatar } from '@platform-ui/highrise'

  const customAvatarSize = ref(73)
</script>

Accessibility

1. When an src is provided for the avatar, make sure to pass alt-text in imgProps.alt for complete a11y support
2. In cases where src and name props are provided but imgProps.alt is not, the name will be used as the fallback for imgProps.alt
3. A11y checks will fail if neither name nor imgProps.alt is provided

Imports

import { HLAvatar, HLBadge } from '@platform-ui/highrise'

Ref: Badge

Props

Name	Type	Default	Description
id *	string	undefined	The id of the element
size	'2xl' | 'xl' | 'lg' | 'md' | 'sm' | 'xs' | '2xs' | '3xs' | number	'xs'	The size of the avatar. Use a preset string or a number for an exact pixel size
objectFit	'fill' | 'contain' | 'cover' | 'none' | 'scale-down'	'fill'	Object fit property of the avatar image
round	boolean	true	Whether the avatar should be circular
src	string	undefined	URL of the avatar image
preferredInitialsBgColor	string	undefined	Custom background color to use when displaying initials. If not provided, a color will be automatically generated based on the name
name	string	undefined	The full name string from which initials will be derived (e.g., "John Doe" → "JD"). At the smallest 3xs size a single initial is shown. Also serves as the fallback shown if src fails to load.
imgProps	ImgHTMLAttributes	{}	Props to attach to the <img /> element when src is passed to avatar

Emits

Name	Arguments	Description
@error	(event: Event) => void	Triggered when the avatar image fails to load. Receives the native image error event.
@click	(event: MouseEvent) => void	Triggered when the avatar is clicked. Receives the native click event.

Slots

Name	Parameters	Description
default	()	Custom content shown when there is no src — e.g. an icon or hand-formatted initials. Overrides the auto-derived initials from name. Ignored while an image is showing.