Avatar

An image element with a fallback for representing the user. The initials show while loading, without a source, and when the image fails to load.

Usage

SAvatar({ src: $r('app.media.startIcon'), fallback: 'SP' })
SAvatar({ src: 'https://example.invalid/me.png', fallback: 'CN' })  // load error → initials
SAvatar({ fallback: 'JD', sizing: 40 })
SAvatar({ fallback: 'AB', sizing: 56 })

Approximate web preview — the HarmonyOS rendering is the reference.

Sizes

sizing: vp, or 'xs' | 'sm' | 'default' | 'md' | 'lg' | 'xl'.

SAvatar({ fallback: 'XS', sizing: 'xs' })
SAvatar({ fallback: 'SM', sizing: 'sm' })
SAvatar({ fallback: 'DF' })
SAvatar({ fallback: 'MD', sizing: 'md' })
SAvatar({ fallback: 'LG', sizing: 'lg' })
SAvatar({ fallback: 'XL', sizing: 'xl' })

Approximate web preview — the HarmonyOS rendering is the reference.

Shapes & status

shape: circle | rounded | square; status: online | away | busy | offline.

SAvatar({ src: $r('app.media.startIcon'), fallback: 'SP', sizing: 'lg' })
SAvatar({ src: $r('app.media.startIcon'), fallback: 'SP', sizing: 'lg', shape: 'rounded' })
SAvatar({ src: $r('app.media.startIcon'), fallback: 'SP', sizing: 'lg', shape: 'square' })
SAvatar({ fallback: 'ON', sizing: 'lg', status: 'online' })
SAvatar({ fallback: 'AW', sizing: 'lg', status: 'away' })
SAvatar({ fallback: 'BS', sizing: 'lg', status: 'busy', shape: 'rounded' })
SAvatar({ fallback: 'OF', sizing: 'lg', status: 'offline' })

Approximate web preview — the HarmonyOS rendering is the reference.

Group

SAvatarGroup overlaps avatars with a background ring and adds "+N".

SAvatarGroup({ fallbacks: ['CN', 'LR', 'ER', 'MK'] })
SAvatarGroup({ fallbacks: ['CN', 'LR', 'ER', 'MK', 'JD', 'AB'], max: 3, sizing: 'md' })
SAvatarGroup({ fallbacks: ['SP', 'CN'], sources: [$r('app.media.startIcon')], extra: 12,
  sizing: 'lg', shape: 'rounded' })

Approximate web preview — the HarmonyOS rendering is the reference.

API

Extracted from the @Param / @Event / @BuilderParam declarations in the library sources.

SAvatar

shadcn-vue Avatar (+ AvatarImage / AvatarFallback): relative flex size-8 shrink-0 overflow-hidden rounded-full. The fallback (initials on bg-muted) shows while the image loads, when src is missing, and when loading fails.

Variants: sizing (vp or xs | sm | default | md | lg | xl), shape (circle | rounded | square), status (presence dot: online | away | busy | offline) and ring (a 2vp background-coloured ring, for overlapping).

Prop	Type	Default	Description
src	ResourceStr | undefined	undefined
fallback	string	''	Initials shown when there is no image.
sizing	number | AvatarSize AvatarSize = 'xs' | 'sm' | 'default' | 'md' | 'lg' | 'xl'	32	Diameter in vp (size-8 = 32) or a named size.
shape	AvatarShape AvatarShape = 'circle' | 'rounded' | 'square'	'circle'
status	AvatarStatus | undefined AvatarStatus = 'online' | 'away' | 'busy' | 'offline'	undefined	Presence dot at the bottom-right.
ring	boolean	false	2vp ring in the background colour (ring-2 ring-background).
label	string | undefined	undefined	Accessible name; defaults to fallback.

SAvatarGroup

Overlapping avatar stack (shadcn's flex -space-x-2 *:ring-2 *:ring-background pattern) with a "+N" bubble. Data-driven, because a slot's children cannot be restyled: pass the initials and (optionally) the images.

Prop	Type	Default	Description
fallbacks	string[]	[]	Initials of each avatar (one avatar per entry).
sources	ResourceStr[]	[]	Image of each avatar, by index (optional, may be shorter).
max	number	0	Avatars shown before the "+N" bubble; 0 = all.
extra	number	0	Additional count not in the lists (e.g. total from a server), added to the "+N" bubble.
sizing	number | AvatarSize AvatarSize = 'xs' | 'sm' | 'default' | 'md' | 'lg' | 'xl'	32
shape	AvatarShape AvatarShape = 'circle' | 'rounded' | 'square'	'circle'
overlap	number | undefined	undefined	Overlap in vp; defaults to a quarter of the diameter (-space-x-2 at 32vp).
label	string | undefined	undefined	Accessible name of the group.