elements
Manual UI Templates Avatar

Avatar

elements man ui/templates/avatar

A user image with an initials fallback, a delayed fallback, a status badge and groups.

Example
import { Avatar, AvatarBadge, AvatarGroup, AvatarGroupCount } from "@elements/ui/avatar";

<Avatar src={user.photo} alt={user.name} />
<Avatar src={user.photo} alt="Ada Lovelace" delayMs={600}>
  <AvatarBadge label="Online" />
</Avatar>
<AvatarGroup label="Project members">
  <Avatar src={a.photo} alt={a.name} />
  <Avatar src={b.photo} alt={b.name} />
  <AvatarGroupCount count={3} />
</AvatarGroup>

Parts

Part What it is
.avatar-image The <img>, always in the DOM, hidden until it loads.
.avatar-fallback Initials or an icon beneath the image.
AvatarBadge .avatar-badge, a status dot at the bottom inline end.
AvatarGroup .avatar-group, overlapping avatars.
AvatarGroupCount .avatar-group-count, the +N chip.

Attributes

Avatar

Attribute Type Default Description
src string "" Image URL. Empty shows the fallback.
alt string "" The person's name: names the avatar and gives the initials.
fallback string "" Fallback text. Default: initials from alt.
delayMs number 0 Wait this long after mount before showing the fallback, so a fast image never flashes it. It runs once; a later src shows the fallback at once.
size "sm" | "md" | "lg" "md" The theme's control heights.
shape "circle" | "square" "circle" square uses the control radius.
lazy boolean false loading="lazy" on the image.
onLoadingStatusChange (status: "idle" | "loading" | "loaded" | "error") => void () => {} Called when the image status changes.
class string "" Extra classes on the root.
attrs Record<string, string | number | boolean | undefined> {} Other attributes for the root.
imageAttrs Record<string, string | number | boolean | undefined> {} Attributes for the <img>: srcset, sizes, crossorigin, referrerpolicy, fetchpriority.

AvatarBadge

Attribute Type Default Description
label string "" Names the status, such as "Online". Empty is decorative.
tone "success" | "accent" | "warning" | "danger" | "muted" "success" Dot color.

AvatarGroup

Attribute Type Default Description
label string "" Names the group.

AvatarGroupCount

Attribute Type Default Description
count number 0 Renders +count.
size "auto" | "sm" | "md" | "lg" "auto" auto matches the group's avatars; a size overrides it.
label string "" Accessible name. Default: "N more".

Slots

Slot Part Content
fallback Avatar Content in place of the initials, such as an <Icon>.
default Avatar An AvatarBadge.
default AvatarBadge An icon inside the dot.
default AvatarGroup Avatars and an AvatarGroupCount.
icon AvatarGroupCount Replaces +count, for an icon.

Data attributes

Attribute Values On
data-status "idle" | "loading" | "loaded" | "error" root
data-delayed present while the fallback waits root
data-starting-style for one frame as the image appears image
data-ending-style while the image goes; visible until its transition ends image
data-size "sm" | "md" | "lg" root
data-shape "circle" | "square" root
data-tone the tone AvatarBadge

Accessibility

  • The image's alt names the avatar. While it loads or after it fails, the fallback is role="img" with the same name.
  • Without alt the avatar is decorative.
  • A badge with a label is announced ("Online"); without one it is hidden.
  • AvatarGroup is a labelled group, and the count reads as "3 more".
  • Loading, failing and the fallback delay change what is visible inside a fixed square, never the layout.

See also