Core · Show content

Avatar

Shows who a person or a team is, with their initials or a photo, in three sizes.

components/avatar.css
No JavaScript
Light · Dark · High contrast
Tested
1 known issue

Example

Three avatars in the small, medium and large sizes, each with the initials of a person.

AB CD EF

Known issues

If a photo does not load, the browser draws its alt text in the box, in the avatar's capitals; a long name can spill past the box. The name is still there for a screen reader.

Code

Copy the markup

HTML

<span class="luz-avatar luz-avatar--md" role="img" aria-label="Carlos Díaz">CD</span>

Next to the person's name, the avatar repeats it: hide it instead.

HTML

<span class="luz-avatar luz-avatar--sm" aria-hidden="true">CD</span> Carlos Díaz

With a photo: the image fills the box, cropped to a square.

HTML

<span class="luz-avatar luz-avatar--md"><img src="/img/ana.jpg" width="36" height="36" alt="Ana Belén"></span>

<span class="luz-avatar luz-avatar--lg"><img src="/img/ana.jpg" width="48" height="48" alt=""></span> Ana Belén

Variants and options

Pick one size modifier.

Without one, the avatar has no size of its own. The content is the initials or one <img>.

Class or content	Effect
`.luz-avatar--sm`	24 × 24 px, extra-small text
`.luz-avatar--md`	36 × 36 px, small text
`.luz-avatar--lg`	48 × 48 px, base text
`<img>` inside	A photo: fills the box, cropped to a square, with the avatar's corners

How it works

An inline box that centres its text, styled by components/avatar.css. No JavaScript.

The initials are set in the mono font, in capitals (text-transform: uppercase).
The colours are the brand tint and the brand text colour, in every mode.
A photo is an <img> at 100% of the box with object-fit: cover and the corners of the avatar (border-radius: inherit). The box does not clip (no overflow: hidden), so initials that outgrow a small box at 200 % text stay readable.

Without JavaScript

Nothing changes: the avatar is HTML and CSS only.

Keyboard and ARIA

An avatar is not interactive and takes no focus.

Initials on their own are an image: role="img" and an aria-label with the full name, so a screen reader does not spell out the initials.
A photo on its own is named by its alt, with the person's name: no role, no aria-label. When the photo is all there is in a link or a button, the alt names the control, so it says the action too: alt="Ana Belén, your account".
Next to the name, an avatar is decoration: aria-hidden="true" on initials, alt="" on a photo.
Inside a link or a button with text, the control's text names it; hide the avatar.

Contrast and focus are in the Design tab.

Design

When to use

Use an avatar to identify a person or an account where space is tight, such as a list of members or the author of a comment.

When not to use

Do not use an avatar as the only way to tell people apart.

Two people can share initials: show the name as text nearby.
For a status or a category, use a tag.
For the portrait of a speaker or a product, a size of its own, use a card with the image frame: see Speakers in the landing page templates. An avatar is 24 to 48 px.

Do and don't

Do Show the name next to the avatar: two people can share initials.

Don't Avatars alone, as the only way to tell people apart: “AB” and “AB” are two different people.

Do Give every photo in a list the same framing: head and shoulders, the face away from the edges, because the box crops it to a square.

Don't Mix photos with initials in a list that could be all one or the other: the people without a photo look like a different kind of member.

Writing the content

Two initials, from the name the person uses.

The accessible name is the full name, never the initials. For a photo, that is its alt.
Use the same size for every avatar in one list.

Contrast and focus

The initials are brand text on the subtle brand tint. A photo is content: the system does not measure it.

Part	Colour on background	Light	Dark	High contrast	Needs
Initials	`--luz-brand-primary` on `--luz-brand-subtle` over `--luz-surface-page`	5.1:1	6.5:1	13.6:1	4.5:1

Measured from the token values of each mode, rounded down. Needs is the WCAG 2.2 AA minimum: 4.5:1 for text, 3:1 for focus rings, borders and icons.

Focus: the avatar takes none. If it is part of a link, the link's ring outlines it.
Not colour alone: the initials and the accessible name carry the person; the colour is the same for everyone.

Tokens it uses

The 7 tokens that components/avatar.css reads, by family. Each family links to its page, with the values in every mode. In Figma they are variables with the same names: see Tokens in Figma.

Color: --luz-brand-primary, --luz-brand-subtle
Typography: --luz-font-mono, --luz-text-base, --luz-text-sm, --luz-text-xs
Radius: --luz-radius-md

Keyboard and ARIA are in the Code tab.