Avatar

A solid colour, one initial, and no outline. Names sit beside each avatar.

<div>
  <ds-row><ds-avatar initial="M" color="#f5aad1"></ds-avatar><ds-text literal>Mika</ds-text></ds-row>
  <ds-row><ds-avatar initial="J" color="#99ff73"></ds-avatar><ds-text literal>Jonas</ds-text></ds-row>
  <ds-row><ds-avatar initial="S" color="#fec20d"></ds-avatar><ds-text literal>Sara</ds-text></ds-row>
  <ds-row><ds-avatar initial="A" color="#ccccff"></ds-avatar><ds-text literal>Ari</ds-text></ds-row>
</div>

Fill an avatar with a colour, or letter it in an ink on the neutral fill. A square one takes a picture’s corners.

<ds-avatar-group aria-label="People">
  <ds-avatar initial="A" color="#99ff73" outlined></ds-avatar>
  <ds-avatar initial="J" color="#f5aad1" outlined></ds-avatar>
  <ds-avatar initial="M" color="#fec20d" outlined></ds-avatar>
</ds-avatar-group>
<ds-avatar-group aria-label="People">
  <ds-avatar initial="E" ink="light-dark(#2e9e1f, #99ff73)" outlined></ds-avatar>
  <ds-avatar initial="高橋" ink="light-dark(#4b44e6, #b3aeff)" outlined></ds-avatar>
  <ds-avatar initial="S" pending></ds-avatar>
</ds-avatar-group>
<ds-avatar shape="square" initial="S" color="#ccccff" label="Studio"></ds-avatar>
<ds-avatar shape="square" size="large" initial="S" color="#ccccff" label="Studio"></ds-avatar>

ds-avatar draws a person or a workspace: a picture, an initial or an icon in a circle, or a square with shape="square". It is one control high (16px times --sf), so it sits inside a one-square row with type in the small size. size="large" is two squares. The product picks who a mark stands for, and handles selecting and acting on it.

<ds-avatar initial="J" label="Joachim"></ds-avatar>
<ds-avatar initial="高橋" label="高橋 由紀"></ds-avatar>
<ds-avatar src="/people/ana.jpg" initial="A" label="Ana"></ds-avatar>
<ds-avatar icon="globe" outlined label="Public"></ds-avatar>

Design examples

Small round identities align with names and quieter roles.

<section class="specimen">
<ds-row class="line" ><span class="mark"><ds-avatar initial="N" label="Nia Vale"></ds-avatar></span><ds-text literal class="grow">Nia Vale</ds-text><ds-text literal tone="muted" size="small">Photographs</ds-text></ds-row><ds-row class="line" ><span class="mark"><ds-avatar initial="O" label="Omar Lee"></ds-avatar></span><ds-text literal class="grow">Omar Lee</ds-text><ds-text literal tone="muted" size="small">Words</ds-text></ds-row><ds-row class="line" ><span class="mark"><ds-avatar initial="R" label="Ruth Park"></ds-avatar></span><ds-text literal class="grow">Ruth Park</ds-text><ds-text literal tone="muted" size="small">Sound</ds-text></ds-row>
</section>
<style>
.specimen { width: 100%; min-width: 0; --cell: calc(20px * var(--sf, 1)); }
.specimen .line { width: 100%; }
.specimen .grow { flex: 1; min-width: 0; }
.specimen .muted { color: var(--ds-text-color-muted); }
.specimen .mono { --ds-typeface-regular: var(--ds-typeface-mono); font-variant-numeric: tabular-nums; }
.specimen .value { width: calc(4 * var(--cell)); text-align: right; }
.specimen .mark { display: inline-flex; align-items: flex-end; width: var(--cell); height: var(--ds-control-height); flex: 0 0 var(--cell); }
.specimen .columns { display: flex; flex-wrap: wrap; gap: var(--cell); }
.specimen .columns > * { min-width: 0; }
.specimen fieldset { border: 0; padding: 0; margin: 0; }
.specimen legend { padding: 0; }
.specimen label { display: flex; align-items: flex-end; gap: calc(var(--cell) / 2); min-height: var(--cell); }
.specimen ds-panel { height: calc(10 * var(--cell)); }
</style>

The same identity at control height and two squares, paired with type.

<section class="specimen">
<ds-row class="line" ><ds-avatar initial="N" label="Nia Vale"></ds-avatar><ds-text literal >Nia Vale</ds-text></ds-row><ds-gap></ds-gap><ds-row class="line" auto><ds-avatar initial="N" size="large" label="Nia Vale"></ds-avatar><div><ds-row class="line" ><ds-text literal strong>Nia Vale</ds-text></ds-row><ds-row class="line" ><ds-text literal tone="muted">Photographer</ds-text></ds-row></div></ds-row>
</section>
<style>
.specimen { width: 100%; min-width: 0; --cell: calc(20px * var(--sf, 1)); }
.specimen .line { width: 100%; }
.specimen .grow { flex: 1; min-width: 0; }
.specimen .muted { color: var(--ds-text-color-muted); }
.specimen .mono { --ds-typeface-regular: var(--ds-typeface-mono); font-variant-numeric: tabular-nums; }
.specimen .value { width: calc(4 * var(--cell)); text-align: right; }
.specimen .mark { display: inline-flex; align-items: flex-end; width: var(--cell); height: var(--ds-control-height); flex: 0 0 var(--cell); }
.specimen .columns { display: flex; flex-wrap: wrap; gap: var(--cell); }
.specimen .columns > * { min-width: 0; }
.specimen fieldset { border: 0; padding: 0; margin: 0; }
.specimen legend { padding: 0; }
.specimen label { display: flex; align-items: flex-end; gap: calc(var(--cell) / 2); min-height: var(--cell); }
.specimen ds-panel { height: calc(10 * var(--cell)); }
</style>

Shape

An avatar is round. shape="square" gives it a picture’s corners: the shared 4px corner, scaled, or --ds-avatar-radius. It follows the surface’s data-ds-shape preference as other corners do. The product decides which marks are square, for example a workspace beside round people.

<ds-avatar shape="square" initial="S" label="Studio"></ds-avatar>
<ds-avatar shape="square" size="large" src="/workspaces/studio.png" initial="S" label="Studio"></ds-avatar>

React takes the same shape on Avatar.

Colour

A filled avatar has no outline by default. Use color with a single initial for the solid circles above; add outlined only when a border is wanted.

There are two ways to colour an avatar:

Fill. color fills the circle with a saved identity colour, and the initial takes black or white, whichever reads on it. Add outlined for the ink line around it.
Ink. ink letters the initial in a person’s colour on the neutral fill, and with outlined draws the line in the same colour. Give it a light-dark() pair, a darker shade that reads on white and a lighter one that reads on black.

<ds-avatar initial="A" color="#99ff73" outlined></ds-avatar>
<ds-avatar initial="J" ink="light-dark(#4b44e6, #b3aeff)" outlined></ds-avatar>

--ds-avatar-background sets the neutral fill behind an inked avatar on tinted paper. pending greys out someone who has not accepted yet, whichever way they are coloured.

Pictures and logos

A picture covers the circle; while it loads, or if it fails, the initial or icon stays. The person drawing (icon="avatar") comes with the avatar itself, so it draws in the first frame; other icons come from the icon library as usual. mask with fit="contain" draws a monochrome mark in the text colour.

A logo is not an avatar. The React Logo sets logo: a brand mark fitted into its image area (size="fill"), unclipped and without the avatar’s corners. Without a picture it shows its initial.

Groups

ds-avatar-group overlaps avatars by 3px. Copy avatar and avatar-group through Sync 1; React products import Avatar, Logo and AvatarGroup from DS1/react/avatar and DS1/react/avatar-group.