Avatar

A lightning-avatar component is an image that represents an object, such as an account or user. By default, the image renders in medium sizing with a rounded rectangle, which is also known as the square variant.

Here’s a basic avatar example.

1<lightning-avatar src="/images/codey.jpg" alternative-text="Codey Bear">
2</lightning-avatar>

To use an image in your org as an avatar, upload the image as a static resource in the Static Resources setup page. Import the image from the @salesforce/resourceUrl module and use it in the src attribute.

lightning-avatar implements the avatar blueprint in the Salesforce Lightning Design System (SLDS). The avatar adapts to SLDS 1 or SLDS 2 styling based on the org’s theme or the container app that you use.

The src attribute resolves the relative path to an image, but sometimes the image path doesn’t resolve correctly because the user is offline or the image has been deleted. To handle an invalid image path, you can provide fallback initials by using the initials attribute or a fallback icon with the fallback-icon-name attribute. These attributes work together if both are specified.

If initials and fallback icon name are provided, the initials are shown and the background color of the fallback icon is used as the background color for the initials. The fallback icon is shown only when the image path is invalid and initials aren’t provided.

This example shows the initials “Sa” if the image path is invalid. The fallback icon “standard:account” provides the background color for the initials. The icon is one of the standard icons in SLDS.

1<template>
2    <lightning-avatar
3        src="/bad/image/url.jpg"
4        initials="Sa"
5        fallback-icon-name="standard:account"
6        alternative-text="Salesforce"
7    >
8    </lightning-avatar>
9</template>

Use a combination of icons, variants, and utility classes to style your avatars.

Although SLDS provides several categories of icons, only icons from the standard and custom categories can be used in lightning-avatar.

Use the variant attribute with one of these values to apply styling.

• square is the default variant, displaying a rectangle avatar with rounded corners
• circle displays a round avatar

This example creates a round avatar.

1<template>
2    <lightning-avatar
3        variant="circle"
4        src="https://v1.lightningdesignsystem.com/assets/images/avatar2.jpg"
5        fallback-icon-name="standard:person_account"
6        alternative-text="Amy Smith"
7    ></lightning-avatar>
8</template>

To apply additional styling, use the SLDS utility classes with the class attribute.

This example adds a margin around the avatar using an SLDS class. The fallback icon is displayed if the image path is invalid.

1<lightning-avatar
2    variant="circle"
3    src="https://v1.lightningdesignsystem.com/assets/images/avatar2.jpg"
4    fallback-icon-name="standard:person_account"
5    alternative-text="Account Name"
6    class="slds-m-around_small"
7>
8</lightning-avatar>

Component styling hooks provide CSS custom properties that use the --slds-c-* prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the SLDS 1 component blueprints for available component styling hooks.

For more information, see Style Components Using Lightning Design System Styling Hooks in the Lightning Web Components Developer Guide.

Use the alternative-text attribute to describe the avatar, such as a user’s initials or name. This description provides the value for the alt attribute in the img HTML tag.