Avatar

<caos-avatar>

a person drawn as a circle: their picture, else their initials, else a glyph

May be placed on a record page, an app’s home page and a page inside an app.

Inputs

Name	Attribute	Description	Type	Default	Required
name	name, markup only	The person the avatar stands for. Its initials are drawn when there is no picture, and it is the avatar’s name for a screen reader.	text	none declared	Optional
src	src, markup only	The address of the picture. When it is missing or fails to load, the initials are drawn instead, and a picture that failed is not tried again until this changes.	text	none declared	Optional
alt	alt, markup only	What a screen reader says in place of the name, when the name alone is not the right description.	text	none declared	Optional
size	size, markup only	The diameter, from the platform size scale: xs, sm, md, lg or xl. The initials scale with it.	text — one of xs, sm, md, lg, xl	md	Optional

Events

This piece raises no events.

Slots

Nothing goes inside this piece.

Styling hooks

Design token	What it controls
--caos-size-xs-height	The diameter at size xs.
--caos-size-sm-height	The diameter at size sm.
--caos-size-md-height	The diameter at size md.
--caos-size-lg-height	The diameter at size lg.
--caos-size-xl-height	The diameter at size xl.
--caos-color-surface-2	The fill behind the initials and the glyph.
--caos-color-border	The 1px edge of the circle.
--caos-color-text-muted	The initials and the glyph.
--caos-radius-pill	The circle.
--caos-font-mono	The typeface of the initials.
--caos-font-weight-label	The weight of the initials.

Methods

Nothing else drives this piece by calling it.

Readable state

Nothing on this piece can be read back.

Styling parts

Part	Which piece of it	When it is there
::part(avatar)	The circle.	Always
::part(image)	The picture, when one is drawn.	Always
::part(initials)	The initials, when they are drawn.	Always

When to use it

The thing shown is a person, and a small recognisable circle helps someone find them in a list or confirm who they are looking at.

What to use instead

• Icon — The mark stands for a kind of thing rather than a particular person.
• Tag — What needs showing is a word about the record, not who it belongs to.

Accessibility

With a name or alt text the avatar is one image with that name, and the picture and initials inside it are hidden, so a screen reader hears the name once rather than two letters. With neither it is decorative and hidden entirely. Initials help someone recognise a person; they never replace the name written beside the avatar.

Examples

Initials

A person with no picture, drawn as the first letters of their first and last names.

{
  "id": "example",
  "section": "Initials",
  "columns": 1,
  "items": [
    {
      "id": "avatar_1",
      "type": "component",
      "key": "avatar",
      "inputs": {
        "name": "Morgan Lee"
      }
    }
  ]
}

<caos-avatar name="Morgan Lee"></caos-avatar>

A picture

A person with a picture, cropped to the circle.

{
  "id": "example",
  "section": "A picture",
  "columns": 1,
  "items": [
    {
      "id": "avatar_1",
      "type": "component",
      "key": "avatar",
      "inputs": {
        "name": "Alex Chen",
        "src": "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 40 40'%3E%3Crect width='40' height='40' fill='%23577590'/%3E%3Ccircle cx='20' cy='16' r='7' fill='%23f1faee'/%3E%3Crect x='8' y='26' width='24' height='16' rx='8' fill='%23f1faee'/%3E%3C/svg%3E"
      }
    }
  ]
}

<caos-avatar name="Alex Chen" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 40 40'%3E%3Crect width='40' height='40' fill='%23577590'/%3E%3Ccircle cx='20' cy='16' r='7' fill='%23f1faee'/%3E%3Crect x='8' y='26' width='24' height='16' rx='8' fill='%23f1faee'/%3E%3C/svg%3E"></caos-avatar>

The size scale

The same person at every step of the platform size scale, from xs to xl.

{
  "id": "example",
  "section": "The size scale",
  "columns": 1,
  "items": [
    {
      "id": "avatar_1",
      "type": "component",
      "key": "avatar",
      "inputs": {
        "name": "Morgan Lee",
        "size": "xs"
      }
    },
    {
      "id": "avatar_2",
      "type": "component",
      "key": "avatar",
      "inputs": {
        "name": "Morgan Lee",
        "size": "sm"
      }
    },
    {
      "id": "avatar_3",
      "type": "component",
      "key": "avatar",
      "inputs": {
        "name": "Morgan Lee",
        "size": "md"
      }
    },
    {
      "id": "avatar_4",
      "type": "component",
      "key": "avatar",
      "inputs": {
        "name": "Morgan Lee",
        "size": "lg"
      }
    },
    {
      "id": "avatar_5",
      "type": "component",
      "key": "avatar",
      "inputs": {
        "name": "Morgan Lee",
        "size": "xl"
      }
    }
  ]
}

<caos-avatar name="Morgan Lee" size="xs"></caos-avatar>
<caos-avatar name="Morgan Lee" size="sm"></caos-avatar>
<caos-avatar name="Morgan Lee" size="md"></caos-avatar>
<caos-avatar name="Morgan Lee" size="lg"></caos-avatar>
<caos-avatar name="Morgan Lee" size="xl"></caos-avatar>

Nobody named

No picture and no name: the user glyph from the platform vocabulary, and nothing for a screen reader.

{
  "id": "example",
  "section": "Nobody named",
  "columns": 1,
  "items": [
    {
      "id": "avatar_1",
      "type": "component",
      "key": "avatar"
    }
  ]
}

<caos-avatar></caos-avatar>