Avatar

sl-avatar

Avatars are used to represent a person or object.

Examples

Basic Avatar

By default, a generic icon will be shown. You can personalize avatars by adding custom icons, initials, and images. You should always provide a label for assistive devices.

<sl-avatar label="User avatar"></sl-avatar>

sl-avatar label="User avatar"

Images

To use an image for the avatar, set the image and label attributes. This will take priority and be shown over initials and icons. Avatar images can be lazily loaded by setting the loading attribute to lazy.

<sl-avatar
  image="https://images.unsplash.com/photo-1529778873920-4da4926a72c2?ixlib=rb-1.2.1&auto=format&fit=crop&w=300&q=80"
  label="Avatar of a gray tabby kitten looking down"
></sl-avatar>
<sl-avatar
  image="https://images.unsplash.com/photo-1591871937573-74dbba515c4c?ixlib=rb-1.2.1&auto=format&fit=crop&w=300&q=80"
  label="Avatar of a white and grey kitten on grey textile"
  loading="lazy"
></sl-avatar>

sl-avatar image="https://images.unsplash.com/photo-1529778873920-4da4926a72c2?ixlib=rb-1.2.1&auto=format&fit=crop&w=300&q=80" label="Avatar of a gray tabby kitten looking down"
sl-avatar image="https://images.unsplash.com/photo-1591871937573-74dbba515c4c?ixlib=rb-1.2.1&auto=format&fit=crop&w=300&q=80" label="Avatar of a white and grey kitten on grey textile" loading="lazy"

Initials

When you don’t have an image to use, you can set the initials attribute to show something more personalized than an icon.

<sl-avatar initials="SL" label="Avatar with initials: SL"></sl-avatar>

sl-avatar initials="SL" label="Avatar with initials: SL"

Custom Icons

When no image or initials are set, an icon will be shown. The default avatar shows a generic “user” icon, but you can customize this with the icon slot.

<sl-avatar label="Avatar with an image icon">
  <sl-icon slot="icon" name="photo"></sl-icon>
</sl-avatar>

<sl-avatar label="Avatar with an archive icon">
  <sl-icon slot="icon" name="archive-box"></sl-icon>
</sl-avatar>

<sl-avatar label="Avatar with a briefcase icon">
  <sl-icon slot="icon" name="briefcase"></sl-icon>
</sl-avatar>

sl-avatar label="Avatar with an image icon"
  sl-icon slot="icon" name="photo"
sl-avatar label="Avatar with an archive icon"
  sl-icon slot="icon" name="archive-box"
sl-avatar label="Avatar with a briefcase icon"
  sl-icon slot="icon" name="briefcase"

Shapes

Avatars can be shaped using the shape attribute.

<sl-avatar shape="square" label="Square avatar"></sl-avatar>
<sl-avatar shape="rounded" label="Rounded avatar"></sl-avatar>
<sl-avatar shape="circle" label="Circle avatar"></sl-avatar>

sl-avatar shape="square" label="Square avatar"
sl-avatar shape="rounded" label="Rounded avatar"
sl-avatar shape="circle" label="Circle avatar"

Avatar Groups

You can group avatars with a few lines of CSS.

<div class="avatar-group">
  <sl-avatar
    image="https://images.unsplash.com/photo-1490150028299-bf57d78394e0?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&q=80&crop=right"
    label="Avatar 1 of 4"
  ></sl-avatar>

  <sl-avatar
    image="https://images.unsplash.com/photo-1503454537195-1dcabb73ffb9?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&crop=left&q=80"
    label="Avatar 2 of 4"
  ></sl-avatar>

  <sl-avatar
    image="https://images.unsplash.com/photo-1456439663599-95b042d50252?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&crop=left&q=80"
    label="Avatar 3 of 4"
  ></sl-avatar>

  <sl-avatar
    image="https://images.unsplash.com/flagged/photo-1554078875-e37cb8b0e27d?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&crop=top&q=80"
    label="Avatar 4 of 4"
  ></sl-avatar>
</div>

<style>
  .avatar-group sl-avatar:not(:first-of-type) {
    margin-left: -1rem;
  }

  .avatar-group sl-avatar::part(base) {
    border: solid 2px var(--sl-color-neutral-0);
  }
</style>

div.avatar-group
  sl-avatar image="https://images.unsplash.com/photo-1490150028299-bf57d78394e0?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&q=80&crop=right" label="Avatar 1 of 4"
  sl-avatar image="https://images.unsplash.com/photo-1503454537195-1dcabb73ffb9?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&crop=left&q=80" label="Avatar 2 of 4"
  sl-avatar image="https://images.unsplash.com/photo-1456439663599-95b042d50252?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&crop=left&q=80" label="Avatar 3 of 4"
  sl-avatar image="https://images.unsplash.com/flagged/photo-1554078875-e37cb8b0e27d?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&crop=top&q=80" label="Avatar 4 of 4"

css:
  .avatar-group sl-avatar:not(:first-of-type) {
    margin-left: -1rem;
  }

  .avatar-group sl-avatar::part(base) {
    border: solid 2px var(--sl-color-neutral-0);
  }

Component Props

Property	Default	Details
`image`	`''`	`string` The image source to use for the avatar.
`label`	`''`	`string` A label to use to describe the avatar to assistive devices.
`initials`	`''`	`string` Initials to use as a fallback when no image is available (1–2 characters max recommended).
`loading`	`'eager'`	`'eager' \| 'lazy'` Indicates how the browser should load the image.
`shape`	`'circle'`	`'circle' \| 'square' \| 'rounded'` The shape of the avatar.
`updateComplete`		A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Slots

Name	Details
`icon`	The default icon to use when no image or initials are present. Works best with `<sl-icon>`.

Learn more about using slots.

Custom Properties

Name	Details
`--size`	The size of the avatar.

Learn more about customizing CSS custom properties.

CSS Parts

Name	Description
`base`	The component’s base wrapper.
`icon`	The container that wraps the avatar’s icon.
`initials`	The container that wraps the avatar’s initials.
`image`	The avatar image. Only shown when the `image` attribute is set.

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

<sl-icon>