Avatar

Avatar is a picture of a person or a thing, with a fallback for when the picture is not there. The image loads off the screen first, and it shows once it is there: a broken image icon never shows. The fallback shows in its place, at once or after a delay.

Anatomy

Avatar.Root holds the status of the image. Avatar.Image is the picture, and Avatar.Fallback is what shows in its place: initials, an icon, a color.

<script>
	import { Avatar } from '@human-kit/ui';
</script>

<Avatar.Root class="size-10 overflow-hidden rounded-full">
	<Avatar.Image src="/ada.jpg" alt="Ada Lovelace" />
	<Avatar.Fallback delay={600}>AL</Avatar.Fallback>
</Avatar.Root>

The image

Avatar.Image loads the image off the screen, and it renders the <img> once the image is there. Without a src, or when the image fails, the <img> never renders and the fallback shows. A new src starts a new load.

The fallback

Avatar.Fallback shows while the image is not on the screen, with the name of the image as its own. Give delay in milliseconds to hold it back while the image loads. A fallback that flashes before a fast image is noise, and 600 hides it on a good connection. It shows at once when the image fails, or when there is no image.

Status

The root has data-status for your styles: loading, loaded or error. onStatusChange gives the same to your code.

Lazy images

Give loading="lazy" to Avatar.Image on a long list: the load then starts when the avatar comes into view, and not on mount. The status is loading until then, and the fallback shows after its delay.

A group

Avatar.Group is a row of avatars, such as the people on a task. It is a role="group": give it a name with aria-label. max limits the avatars on the screen, and the ones past it render nothing, thus they load no image. Avatar.Count shows how many they are, as +N. The screen reader hears "N more", in the locale of LocaleProvider.

Usage guidelines

• Give alt the name of the person or the thing. Give an empty alt when the name is beside the avatar already, thus a screen reader does not read it twice. The fallback follows the alt: it takes the name, or it hides.
• Give the root a size and overflow: hidden, and the image object-fit: cover.
• Give delay to the fallback on a list of avatars: a list that flashes initials is noise.
• Give a group a name with aria-label. A row of pictures with no name is a row a screen reader cannot tell apart from the content around it.

Accessibility

• The image is an <img> with your alt. The root has no role of its own.
• The fallback takes the name of the image: it is a role="img" named with the alt. A screen reader hears the name, and not the letters of the initials. An empty alt hides it. Without an image, it is plain content.
• Avatar.Group is a role="group" named with your aria-label. Avatar.Count is a role="img" named "N more".
• Nothing in the avatar is focusable.

API reference

Root

The picture and its fallback. It holds the status of the image, and it has no role of its own.

* required. Native HTML attributes of the underlying element are also accepted.

Image

The picture. It loads the image off the screen first, and it renders the `<img>` once the image is there.

* required. Native HTML attributes of the underlying element are also accepted.

Fallback

What shows in place of the image, while the image is not on the screen, named with its `alt`. `delay` holds it back while the image loads.

* required. Native HTML attributes of the underlying element are also accepted.

Group

A row of avatars, as a `role="group"` named with `aria-label`. `max` limits the avatars on the screen.

* required. Native HTML attributes of the underlying element are also accepted.

Count

The count of avatars past the `max` of the group, as `+N`, and "N more" for the screen reader. It renders only while there are some.

* required. Native HTML attributes of the underlying element are also accepted.