Avatar

Display user profile images, initials, or icons with status indicators, badges, and grouping.

JSBO

<script setup lang="ts">
import { VxAvatar } from 'veloxui'
</script>

<template>
  <VxAvatar src="https://example.com/photo.jpg" name="John Doe" />
  <VxAvatar name="Jane Smith" />
  <VxAvatar name="Bob" bg-color="#3b82f6" />
  <VxAvatar />
</template>

Sizes

Available in 5 preset sizes or any custom pixel value.

XSSMDFLGXL80

<template>
  <VxAvatar name="Alice" size="xs" />   <!-- 24px -->
  <VxAvatar name="Alice" size="sm" />   <!-- 32px -->
  <VxAvatar name="Alice" />             <!-- 40px default -->
  <VxAvatar name="Alice" size="lg" />   <!-- 48px -->
  <VxAvatar name="Alice" size="xl" />   <!-- 64px -->
  <VxAvatar name="Alice" :size="80" />  <!-- 80px custom -->
</template>

Shapes

<template>
  <VxAvatar src="..." shape="circle" />
  <VxAvatar src="..." shape="square" />
</template>

Initials

Initials are auto-generated from name. Colors are deterministic per name.

AJBOCBDPEVFC

<template>
  <VxAvatar name="Alice Johnson" />  <!-- AJ -->
  <VxAvatar name="Bob" />           <!-- BO -->
  <VxAvatar name="Charlie Brown" /> <!-- CB -->
</template>

Custom Colors

REGRBLPUDA

<template>
  <VxAvatar name="Alice" bg-color="#ef4444" />
  <VxAvatar name="Alice" bg-color="#18181b" color="#fafafa" />
</template>

Status Indicator

<template>
  <VxAvatar src="..." status="online" />
  <VxAvatar src="..." status="offline" />
  <VxAvatar src="..." status="busy" />
  <VxAvatar src="..." status="away" />
</template>

Status Ring

Use status-ring to show the status as a colored ring around the avatar instead of a dot.

AUOF

<template>
  <VxAvatar src="..." status="online" status-ring />
  <VxAvatar src="..." status="busy" status-ring />
</template>

Notification Badge

Show a number badge or a simple dot indicator.

39999+DIEV

<script setup lang="ts">
import { VxAvatar } from 'veloxui'
</script>

<template>
  <!-- Number badge (caps at 99+) -->
  <VxAvatar src="..." :badge="3" />
  <VxAvatar src="..." :badge="150" />  <!-- shows "99+" -->

  <!-- Dot badge -->
  <VxAvatar name="Diana" dot />

  <!-- Custom badge color -->
  <VxAvatar name="Eve" dot badge-color="#3b82f6" />
</template>

Badge Position

TR1TL2BR3BL4

<template>
  <VxAvatar :badge="1" badge-position="top-right" />
  <VxAvatar :badge="2" badge-position="top-left" />
  <VxAvatar :badge="3" badge-position="bottom-right" />
  <VxAvatar :badge="4" badge-position="bottom-left" />
</template>

Clickable

Make the avatar interactive with clickable. Renders as a <button> for accessibility with focus ring and press feedback.

<script setup lang="ts">
import { VxAvatar } from 'veloxui'

function onAvatarClick() {
  alert('Avatar clicked!')
}
</script>

<template>
  <VxAvatar src="..." clickable @click="onAvatarClick" />
</template>

Tooltip

Hover to see the name as a native tooltip.

JS

<template>
  <VxAvatar src="..." tooltip="John Doe - Admin" />
  <VxAvatar name="Jane" tooltip="Jane Smith - Editor" />
</template>

Lazy Loading

Add lazy to defer image loading until the avatar is near the viewport.

<template>
  <VxAvatar src="..." lazy />
</template>

Srcset (Retina)

Provide srcset for responsive/retina images.

<template>
  <VxAvatar
    src="photo-1x.jpg"
    srcset="photo-1x.jpg 1x, photo-2x.jpg 2x, photo-3x.jpg 3x"
  />
</template>

Bordered

AL

<template>
  <VxAvatar src="..." bordered />
  <VxAvatar src="..." bordered border-color="#3b82f6" />
</template>

Fallback Slot

Use the fallback slot for completely custom fallback content when no image or name is provided.

🤖AI

<template>
  <VxAvatar size="lg" bg-color="#18181b">
    <template #fallback>
      <span style="font-size: 20px;">🤖</span>
    </template>
  </VxAvatar>
</template>

Image Fallback

When the image fails to load, falls back to initials, then fallback slot, then default user icon.

<template>
  <VxAvatar src="https://broken.url" name="Fallback User" />
  <VxAvatar src="https://broken.url" />
</template>

Avatar Group

Stack avatars with overlap. Hover to pop out individual avatars.

EV

<script setup lang="ts">
import { VxAvatar, VxAvatarGroup } from 'veloxui'
</script>

<template>
  <VxAvatarGroup size="lg">
    <VxAvatar src="..." name="Alice" />
    <VxAvatar src="..." name="Bob" />
    <VxAvatar src="..." name="Charlie" />
    <VxAvatar name="Eve" />
  </VxAvatarGroup>
</template>

Group with +N Overflow

Set max to limit visible avatars. Remaining count shows as a "+N" badge.

+4

<template>
  <VxAvatarGroup size="lg" :max="3">
    <VxAvatar src="..." name="Alice" />
    <VxAvatar src="..." name="Bob" />
    <VxAvatar src="..." name="Charlie" />
    <VxAvatar src="..." name="Diana" />
    <VxAvatar src="..." name="Eve" />
    <!-- Shows "+2" overflow badge -->
  </VxAvatarGroup>
</template>

Group Overlap Control

Adjust how much avatars overlap with the overlap prop (percentage of avatar size).

overlap=15

overlap=25

overlap=40

<template>
  <VxAvatarGroup :overlap="15">...</VxAvatarGroup>  <!-- less overlap -->
  <VxAvatarGroup :overlap="25">...</VxAvatarGroup>  <!-- default -->
  <VxAvatarGroup :overlap="40">...</VxAvatarGroup>  <!-- more overlap -->
</template>

Square Group

DI

<template>
  <VxAvatarGroup shape="square" size="lg">
    <VxAvatar src="..." />
    <VxAvatar name="Diana" />
  </VxAvatarGroup>
</template>

Avatar Props

Prop	Type	Default	Description
src	string	''	Image URL
srcset	string	''	Responsive image srcset
alt	string	''	Image alt text
name	string	''	Name for initials and auto-color
size	'xs' | 'sm' | 'default' | 'lg' | 'xl' | number	'default'	Avatar size
shape	'circle' | 'square'	'circle'	Avatar shape
color	string	''	Text/icon color
bgColor	string	''	Background color (overrides auto-color)
icon	Component	—	Custom icon component
bordered	boolean	false	Show border
borderColor	string	''	Custom border color
status	'online' | 'offline' | 'busy' | 'away'	''	Status indicator
statusPosition	'top-right' | 'bottom-right' | 'top-left' | 'bottom-left'	'bottom-right'	Status dot position
statusRing	boolean	false	Show status as ring instead of dot
badge	string | number	—	Badge number (caps at 99+)
dot	boolean	false	Show dot badge
badgePosition	'top-right' | 'bottom-right' | 'top-left' | 'bottom-left'	'top-right'	Badge/dot position
badgeColor	string	'#ef4444'	Badge/dot color
clickable	boolean	false	Make interactive (renders as button)
tooltip	string	''	Native tooltip on hover
lazy	boolean	false	Lazy load image

AvatarGroup Props

Prop	Type	Default	Description
max	number	0	Max visible avatars (0 = all)
size	AvatarSize	'default'	Size for all children
shape	'circle' | 'square'	'circle'	Shape for all children
bordered	boolean	true	Border all children
overlap	number	25	Overlap percentage (0-100)

Events

Event	Type	Description
error	(event)	Image failed to load
click	(event)	Avatar clicked (only when clickable)

Slots

Slot	Description
default	Custom overlay content
fallback	Custom fallback when no image/name/icon