Accessibility: Full

Translations: Not Needed

Migration Guide: Full

Avatar

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

Default

CM

Vue

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

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

All Sizes

CM

CM

CM

CM

CM

CM

CM

CM

CM

CM

CM

CM

CM

CM

CM

CM

Custom Size

Round

<!-- Round Avatars (Default) -->
<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>

Square

<!-- Square Avatars -->
<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>

Custom Size

<!-- Custom Size -->
<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>

Avatar with Initials

JD

AS

RJ

Vue

<HLAvatar id="example-avatar-initials" size="2xl" name="John Doe" />
<!-- Will automatically display "JD" -->

Avatar with Image

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

Vue

<!-- Avatar with image and event handlers -->
<HLAvatar
  id="example-avatar-image"
  size="2xl"
  src="https://example.com/avatar.jpg"
  :imgProps="{
    alt: 'old rusted car in an open field in a cloudy background',
  }"
  name="John Doe"
  @error="handleImageError"
  @load="handleImageLoad"
  @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"
/>

Avatar with Status Indicator

CM

AB

Vue

<HLBadge size="2xl" dot :offset="[-10, 10]" id="example-avatar-indicator-2xl">
  <HLAvatar size="2xl">CM</HLAvatar>
</HLBadge>
<HLBadge size="sm" dot :offset="[-5, 5]">
  <HLAvatar size="sm" :round="false">CM</HLAvatar>
  <template #value>
    <img
      src="https://picsum.photos/seed/FeB6P/640/480"
      :imgProps="{
        alt: 'old rusted car in an open field in a cloudy background',
      }"
    />
  </template>
</HLBadge>

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.

Custom Avatar Sizes

Custom size (px)

CMCM

Vue

<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, HLInputNumber } from '@platform-ui/highrise'

  const customAvatarSize = ref(123)
</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
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")
imgProps	ImgHTMLAttributes	{}	Props to attach to the <img /> element when src is passed to avatar

Emits

Name	Arguments	Description
@error	() => void	Triggered when the avatar image fails to load
@click	() => void	Triggered when the avatar is clicked

Slots

Name	Parameters	Description
default	()	The default content slot