Avatar
An avatar shows who or what something belongs to: a photo, or initials on a colored background.
<tk-avatar shape="circle" name="Mira Petrova"></tk-avatar> <tk-avatar name="Acme Corp"></tk-avatar>
Anatomy
| Part | What it is |
|---|---|
tk-avatar |
the frame, a circle or a rounded square |
| image | the photo from src, with a thin inner border |
| initials | white letters from name, on a colored background |
badge slot |
an optional |
Shape
<tk-avatar shape="circle" name="Mira Petrova"></tk-avatar> <tk-avatar name="Acme Corp"></tk-avatar> <tk-avatar name="Release bot"></tk-avatar>
circle: live people only.square(default): everything else: organizations, workspaces, teams, products, and bots, even a bot with a name and a face.
Use one shape per kind of thing across your product.
Sizes
<tk-avatar name="Mira Petrova" size="20"></tk-avatar> <tk-avatar name="Mira Petrova" size="24"></tk-avatar> <tk-avatar name="Mira Petrova"></tk-avatar> <tk-avatar name="Mira Petrova" size="40"></tk-avatar> <tk-avatar name="Mira Petrova" size="48"></tk-avatar> <tk-avatar name="Mira Petrova" size="64"></tk-avatar>
size |
Square corner | Initials | Typical place |
|---|---|---|---|
20 |
radius-4 |
one letter, 12px | inline with text |
24 |
radius-4 |
12px | dense lists, table cells |
32 (default) |
radius-8 |
14px | list rows, comments |
40 |
radius-8 |
16px | cards, headers |
48 |
radius-8 |
18px | page headers |
64 |
radius-12 |
24px | profiles |
Image and initials
<tk-avatar shape="circle" src="/photos/mira.jpg" name="Mira Petrova"></tk-avatar>
An avatar always shows something:
- The image, when
srcloads. If it fails, the avatar falls back on its own. - Initials, when there's no image: the first letters of the first and last words of
name("Mira Petrova" shows MP). - The background alone, when there's no image and no
name.
Color
<tk-avatar name="Design team" color="purple"></tk-avatar> <tk-avatar name="Support team" color="teal"></tk-avatar>
The background is one of twelve colors: blue, indigo, red, orange, yellow,
green, mint, teal, cyan, purple, pink, brown. Without color, the name picks
one, and the same name always gets the same color. The backgrounds look the same in every
theme.
Badge
<tk-avatar shape="circle" name="Mira Petrova"> <tk-badge slot="badge" dot tone="success" label="Online"></tk-badge> </tk-avatar> <tk-avatar size="48" name="Acme Corp"> <tk-badge slot="badge" tone="error" treatment="solid" count="4" label="4 incidents"></tk-badge> </tk-avatar>
- A
countbadge goes on the top corner, for notifications. A dot or a label badge goes on the bottom corner, for presence. The avatar picks the corner. - Use one badge per avatar. A dot fits sizes 24 to 48; a count reads best from 40.
- The badge has a 2px ring in the page color. On a surface other than
surface/default, restyle the ring. - Inside an
Avatar group , badges are hidden.
When to use
- Use an avatar to show a person or an entity, in list rows, comments, cards, and assignee fields.
- Keep the name in text nearby. A photo alone doesn't identify anyone for everyone.
- To make an avatar clickable, put it inside a button or a link. The avatar itself takes no focus.
- For several people in a row, use an
Avatar group .
Do / Don't
| ✅ Do | ❌ Don't |
|---|---|
| Use a circle for a person who wrote a comment | Use a circle for a workspace because it looks friendlier |
| Use a square for a bot, even with a face image | Give a bot a circle to make it feel human |
Leave label unset next to a visible name |
Set label next to the same name; it's read twice |
Set label when the avatar stands alone |
Leave an avatar-only row silent |
| Let the avatar handle missing images | Hide the avatar or build initials yourself |
| Put a count badge on a size 40 or larger avatar | Put a count on a tiny avatar, or a count and a dot on one |
Related
Avatar group : overlapping avatars with a "+N" overflow.Badge : the corner indicator.
API
Attributes
| Attribute | Type | Default | What it does |
|---|---|---|---|
shape |
square | circle |
square |
circle for live people only |
size |
20 | 24 | 32 | 40 | 48 | 64 |
32 |
width and height in px |
src |
string | the image URL | |
name |
string | the source of the initials and the color; not read by screen readers | |
color |
one of the twelve colors | from name |
the background color |
label |
string | announces the avatar with this name; unset, the avatar is hidden from screen readers |
Slots
| Slot | Content |
|---|---|
badge |
one tk-badge |
Events
None.
Tokens
| Element | Tokens |
|---|---|
| square corner | radius-4, radius-8, radius-12 by size |
| circle | radius-full |
| background | {color}-900, -800, -700, -500, -50 primitives, the same in every theme |
| initials | white, font-weight-medium, font-size-xs to font-size-2xl by size |
| image border | border/subtle |
| badge ring | surface/default |
Accessibility
Built in:
- Without
label, the avatar is hidden from screen readers, for the usual case of an avatar next to the visible name. - With
label, the avatar is an image with that name. nameis never read out, so nothing is announced twice.
Your part:
- Set
labelwhen the avatar is the only thing that says who it is, such as in an avatar-only toolbar. Usually it is the same asname. - Don't set
labelnext to the same visible name. - A hidden avatar hides its badge too. Say the status in text nearby, or put it in
label: "Mira Petrova, online". - Photos are your content and have no contrast guarantee. Don't rely on the image alone.