Avatar

An avatar shows a person or a thing at a small fixed size. Most of the component is about the image not being there: it is probed before it is rendered, and the fallback holds the space until the image is known to be usable — so the layout never jumps and a broken source never leaves a torn icon behind.

AvatarGroup stacks a set of them and hands each one its size.

import { Avatar, AvatarFallback, AvatarImage } from "ropav";

JD

variant

 unsetdefaultsoft

color

 unsetdefaultaccentsuccesswarningdanger

size

 xssmmdlg

<Avatar>
  <AvatarFallback>JD</AvatarFallback>
</Avatar>

Image and fallback

GHKJ

avatar-image.vue

<script setup lang="ts">
import { Avatar, AvatarFallback, AvatarImage } from "ropav";

// Data URIs so the demo needs nothing from the network.
// Valid as a URL, not decodable as a PNG — which is a load failure with nothing to fetch.
const broken = "data:image/png;base64,cm9wYXY=";

const portrait =
  "data:image/svg+xml;utf8," +
  encodeURIComponent(
    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
       <rect width="64" height="64" fill="#0485f7" />
       <circle cx="32" cy="25" r="12" fill="#bfe0ff" />
       <circle cx="32" cy="58" r="19" fill="#bfe0ff" />
     </svg>`,
  );
</script>

<template>
  <Avatar size="lg">
    <AvatarImage alt="" :src="portrait" />
    <AvatarFallback :delay-ms="600">AL</AvatarFallback>
  </Avatar>

  <Avatar size="lg">
    <AvatarImage alt="" :src="broken" />
    <AvatarFallback>GH</AvatarFallback>
  </Avatar>

  <Avatar color="accent" size="lg" variant="soft">
    <AvatarFallback>KJ</AvatarFallback>
  </Avatar>
</template>

delay-ms holds the fallback back for that long before it may render, so an image that arrives quickly never flashes initials on the way. It only ever reveals the fallback — nothing puts it back — so a cached image that resolves immediately shows no fallback at all, delay or not.

loading-status-change reports loading, loaded or error for a caller that wants to do something else with the failure.

Accessibility

• alt defaults to empty, which marks the image decorative. An avatar almost always sits beside the name it belongs to, and the fallback carries the initials, so a description here usually repeats what is already on the page. Set it where the avatar is genuinely the only thing naming the person. Leaving the attribute off altogether is never right, and the component never does.
• The fallback's colour is a decoration, not a signal: two people with the same initials are told apart by the name beside the avatar, not by the shade behind it.
• variant="soft" and color change the fallback's appearance only. An image covers them.

API

Avatar

Prop	Type	Default	Description
color	"default" | "accent" | "success" | "warning" | "danger"	—	Fallback color.
size	"xs" | "sm" | "md" | "lg"	"md"	Avatar size.
variant	"default" | "soft"	—	Avatar variant.

Slots: default.

AvatarFallback

Prop	Type	Default	Description
color	"default" | "accent" | "success" | "warning" | "danger"	—	Overrides the fallback color inherited from the root.
delayMs	number	—	How long to hold the fallback back before it may render, so an image that arrives quickly never flashes one. Without it the fallback shows immediately.

Slots: default.

AvatarImage

Prop	Type	Default	Description
alt	string	—	Alternative text, forwarded to the rendered img. Defaults to empty, which marks the image decorative: an avatar sits beside the name it belongs to, and the fallback carries the initials, so a description here usually repeats what is already on the page. Omitting the attribute altogether is never right.
crossOrigin	"" | "anonymous" | "use-credentials"	—	Forwarded to the probe image so the request matches the rendered one.
loading	"eager" | "lazy"	—	Native loading behaviour.
referrerPolicy	"" | "no-referrer" | "no-referrer-when-downgrade" | "origin" | "origin-when-cross-origin" | "same-origin" | "strict-origin" | "strict-origin-when-cross-origin" | "unsafe-url"	—	Forwarded to the probe image.
sizes	string	—	Responsive size hints.
src	string	—	Image source.
srcSet	string	—	Responsive source set. Rendered as the srcset attribute.

Event	Payload
error	Event
load	Event
loadingStatusChange	ImageLoadingStatus