Avatar

<zeno-avatar>Data displaySource

A picture of a person or thing, falling back to initials or an icon when there is no image.

import '@usezeno/tokens/css';
import '@usezeno/core/web-components';

Examples

Initials

Without an image, the avatar shows initials. They come from name: the first and last word, or the first two letters of a single word. initials sets them directly.

<zeno-avatar name="Ada Lovelace"></zeno-avatar>
<zeno-avatar name="Grace Brewster Hopper"></zeno-avatar>
<zeno-avatar name="Katherine"></zeno-avatar>
<zeno-avatar name="Quality team" initials="QA"></zeno-avatar>

Sizes

<zeno-avatar size="xs" name="Ada Lovelace"></zeno-avatar>
<zeno-avatar size="sm" name="Ada Lovelace"></zeno-avatar>
<zeno-avatar size="md" name="Ada Lovelace"></zeno-avatar>
<zeno-avatar size="lg" name="Ada Lovelace"></zeno-avatar>
<zeno-avatar size="xl" name="Ada Lovelace"></zeno-avatar>
<zeno-avatar size="2xl" name="Ada Lovelace"></zeno-avatar>

Shapes and border

<zeno-avatar shape="circle" name="Ada Lovelace"></zeno-avatar>
<zeno-avatar shape="rounded" name="Ada Lovelace"></zeno-avatar>
<zeno-avatar shape="square" name="Ada Lovelace"></zeno-avatar>
<zeno-avatar bordered name="Ada Lovelace"></zeno-avatar>

Icon

icon shows a registered icon in place of initials. With no image, icon, name or initials, the avatar shows a person icon. alt gives the accessible name.

<zeno-avatar icon="settings" alt="Settings"></zeno-avatar>
<zeno-avatar icon="star" alt="Favourites" shape="rounded"></zeno-avatar>
<zeno-avatar alt="Unknown user"></zeno-avatar>

Clickable

With clickable the avatar can take focus, and Enter or Space fire a click.

Not opened yet.

<zeno-avatar clickable name="Ada Lovelace"></zeno-avatar>
<p data-result>Not opened yet.</p>

let count = 0;
document.querySelector('zeno-avatar').addEventListener('click', () => {
  count += 1;
  document.querySelector('[data-result]').textContent = 'Opened ' + count + ' times.';
});

Attributes and properties

Property	Attribute	Type	Default	Description
src	src	string	–
alt	alt	string	–
name	name	string	–
initials	initials	string	–
icon	icon	string	–
size	sizereflects	'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'	'md'
shape	shapereflects	'circle' | 'square' | 'rounded'	'circle'
variant	variantreflects	'solid' | 'soft' | 'outlined' | 'plain'	'solid'
status	statusreflects	'online' | 'offline' | 'busy' | 'away'	–
badge	badge	number	–
bordered	borderedreflects	boolean	false
clickable	clickablereflects	boolean	false
testId	–	string	–	Test ID for automated testing From ZenoElement.

Methods

Method	Description
focus(): void	Focus the component or its first focusable element From ZenoElement.
blur(): void	Blur the component or its focused element From ZenoElement.

Events

Event	Detail	Description
load	–	The image loaded.
error	–	The image failed to load and the fallback is showing.

Slots

This element has no slots.

CSS parts

Part
badge
base
icon
image
initials
status

CSS custom properties

This element documents no custom properties of its own. Style it through its parts and through the tokens it reads.

The element's own source reads no tokens.

Accessibility

Keyboard

Key	What it does
Tab	Moves focus to the avatar, only when it is clickable.
EnterSpace	Fires a click on the avatar, only when it is clickable.

Forms

This element is not a form control. It adds nothing to a form's data.

Notes

• The avatar has role="img". With clickable it has role="button" and tabindex="0".
• The accessible name is the first of these that is set: aria-label, alt, name. With none of them it is “Avatar”.
• The initials and the icon are not announced. Only the name is.
• An image set with src is a native <img>. If it fails to load, the avatar falls back to the icon or the initials.

Tests and known gaps

• No tests of its own. The only check is that the element registers and renders (smoke.test.ts).
• Not checked with axe-core.
• Has no Storybook story.

18 of the 23 properties, methods, events, slots and parts above have no description in the source

• the property src
• the property alt
• the property name
• the property initials
• the property icon
• the property size
• the property shape
• the property variant
• the property status
• the property badge
• the property bordered
• the property clickable
• the part badge
• the part base
• the part icon
• the part image
• the part initials
• the part status

Known gaps:

• variant does nothing. Its values are solid, soft, outlined and plain, but the styles are written for primary, secondary, success, warning, error and info, which the type does not allow. Every avatar is grey.
• The status dot and the badge count are cut off. They are placed on the edge of the avatar, and the avatar clips everything outside its shape. On a round avatar only a small part of each is visible.
• status and badge are not announced. Their labels are on elements without a role, inside role="img", which hides its children. The status is shown by colour only.
• The texts “Avatar”, “Status: …” and “… notifications” are English and cannot be changed.
• After one image fails to load, the avatar never tries an image again, also when src changes to a good address.
• The .avatar-group-item host style uses --avatar-size, which is only defined on the inner element. The overlap margin it should give is never applied, and there is no avatar group element.