Avatar

avonni-avatar

An avatar displays a thumbnail representing a user or entity, with support for images, initials, icons, presence and status indicators.

Overview

Avatar is a Lightning Web Component that displays a user or entity identity using an image, initials, or an icon fallback.

Use it in your own Lightning Web Components to represent people, accounts, or records. You control the shape, size, detail text, status and presence indicators, tags, and action buttons—all through the component's attributes.

Use Cases

• Record headers: Show the owner or primary contact of a record with their name and role.
• List items: Display a compact identity next to each row in a custom list.
• User menus: Combine an image with status and presence indicators.
• Team rosters: Represent users with initials when no photo is available.
• Status displays: Surface approval or lock status with the status badge.

---

Size Guidelines

Size	Use Case
x-small / small	Inline with text, dense list rows.
medium	Default for most list and card layouts.
large and up	Record headers and profile displays (enables tertiary text).

---

Use Case Examples

Example 1: User identity in a record header

Scenario: Show the record owner with their name, role, and online presence at the top of a custom record page component.

<!-- recordHeader.html -->
<template>
    <avonni-avatar
        alternative-text="Jane Cooper, Product Designer"
        fallback-icon-name="standard:user"
        initials="JC"
        primary-text="Jane Cooper"
        secondary-text="Product Designer"
        size="x-large"
        presence="online"
        variant="circle"
    ></avonni-avatar>
</template>

Result: A large circular avatar with the owner's initials, name, role, and an online presence dot.

Example 2: Avatar with an action menu

Scenario: Let users trigger actions (view profile, send message) directly from the avatar.

<!-- teamMember.html -->
<template>
    <avonni-avatar
        alternative-text="Jane Cooper"
        fallback-icon-name="standard:user"
        initials="JC"
        size="large"
        actions={actions}
        action-position="bottom-right"
        onactionclick={handleActionClick}
    ></avonni-avatar>
</template>

// teamMember.js
import { LightningElement } from 'lwc';

export default class TeamMember extends LightningElement {
    actions = [
        { label: 'View profile', name: 'view' },
        { label: 'Send message', name: 'message' }
    ];

    handleActionClick(event) {
        const actionName = event.detail.name; // 'view' or 'message'
    }
}

Result: An avatar with a button menu; clicking an action fires actionclick with the action's name.

---

Specifications

Attributes

Name	Description	Type	Default	Required
action-menu-icon	The Lightning Design System icon name for a custom menu icon. Unused if there is only one action.	String	"utility:down"
action-position	Position of the action button or menu relative to the avatar. Valid values include top-right, bottom-right, bottom-left or top-left.	String	"bottom-left"
actions	Array of action objects. If the array contains a single action, it is displayed as a button icon. Otherwise, actions are placed in a button menu with a label and icon.	AvonniAvatarAction[]	—
alternative-text	The alternative text used to describe the avatar, which is displayed as hover text on the image.	String	"Avatar"	Yes
entity-icon-name	The Lightning Design System name of the icon used as a fallback for the entity icon when the image fails to load. The initials fallback relies on this for its background color. Names are written in the format 'standard:account' where 'standard' is the category, and 'account' is the specific icon to be displayed. Only icons from the standard and custom categories are allowed.	String	—
entity-initials	Entity initials. If the record name contains two words, like first and last name, use the first capitalized letter of each. For records that only have a single word name, use the first two letters of that word using one capital and one lower case letter.	String	—
entity-position	Position of the entity icon. Valid values include top-left, top-right, bottom-left and bottom-right.	String	"top-left"
entity-src	The URL for the entity image.	String	—
entity-title	Entity title to be shown as a tooltip on hover over the presence icon.	String	"Entity"
entity-variant	The variant changes the shape of the entity. Valid values are empty, circle, and square.	String	"square"
fallback-icon-name	The Lightning Design System name of the icon used as a fallback when the image fails to load. The initials fallback relies on this for its background color. Names are written in the format 'standard:account' where 'standard' is the category, and 'account' is the specific icon to be displayed. Only icons from the standard and custom categories are allowed.	String	—
href	The URL of the page the link goes to.	String	—
icon-position	The position of the avatar icon. Valid values are start, center, end.	String	"center"
initials	If the record name contains two words, like first and last name, use the first capitalized letter of each. For records that only have a single word name, use the first two letters of that word using one capital and one lower case letter.	String	—
presence	Presence of the user to display. Valid values include online, busy, focus, offline, blocked and away.	String	—
presence-position	Position of the presence icon. Valid values include top-left, top-right, bottom-left and bottom-right.	String	"bottom-right"
presence-title	Presence title to be shown as a tooltip on hover over the presence icon.	String	"Presence"
primary-text	Primary text to display, usually the name of the person.	String	—
primary-text-url	Primary text url	String	—
secondary-text	Secondary text to display, usually the role of the user.	String	—
size	The size of the avatar. Valid values are x-small, small, medium, large, x-large , xx-large and xxx-large.	String	"medium"
src	The URL for the image.	String	—	Yes
status	Status of the user to display. Valid values include approved, locked, declined and unknown.	String	—
status-position	Position of the status icon. Valid values include top-left, top-right, bottom-left and bottom-right.	String	"top-right"
status-title	Status title to be shown as a tooltip on hover over the status icon.	String	"Status"
tags	Array of tag objects. The tags are displayed as chips in the details.	AvonniAvatarTag[]	—
target	The target of the link.	String	—
tertiary-text	Tertiary text to display, usually the status of the user. The tertiary text will only be shown when using size x-large, xx-large and xxx-large.	String	—
text-position	Position of the details text, relatively to the avatar. Valid values include right, left or center.	String	"right"
variant	The variant changes the shape of the avatar. Valid values are circle and square.	String	"square"

Methods

Name	Description	Argument Name	Argument Type	Argument Description
getBackgroundColor	Get the background color of the icon.

Custom Events

actionclick

The event fired when a user clicks on an action.

The actionclick event returns the following parameters.

Parameter	Type	Description
name	string	The action name.

The event properties are as follows.

Property	Value	Description
bubbles	true	This event bubbles up through the DOM.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

actionclick

The event fired when a user clicks on an action.

The actionclick event returns the following parameters.

Parameter	Type	Description
name	string	The action name.

The event properties are as follows.

Property	Value	Description
bubbles	true	This event bubbles up through the DOM.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

Styling Hooks

CSS Variable	Type	Default
--avonni-avatar-color-border	color	transparent
--avonni-avatar-radius-border	dimension	0.25rem
--avonni-avatar-scale	sizing	—
--avonni-avatar-sizing-border	sizing	0
--avonni-avatar-styling-border	styling	solid
--avonni-avatar-image-object-fit	string	—
--avonni-avatar-primary-text-color	color	#000000
--avonni-avatar-primary-text-font-size	font	0.875rem
--avonni-avatar-primary-text-font-style	font	normal
--avonni-avatar-primary-text-font-weight	font	700
--avonni-avatar-primary-text-font-family	font	—
--avonni-avatar-primary-text-line-height	dimension	—
--avonni-avatar-primary-text-letter-spacing	dimension	—
--avonni-avatar-secondary-text-color	color	#696969
--avonni-avatar-secondary-text-font-size	font	0.8125rem
--avonni-avatar-secondary-text-font-style	font	normal
--avonni-avatar-secondary-text-font-weight	font	400
--avonni-avatar-secondary-text-font-family	font	—
--avonni-avatar-secondary-text-line-height	dimension	—
--avonni-avatar-secondary-text-letter-spacing	dimension	—
--avonni-avatar-tertiary-text-color	color	#696969
--avonni-avatar-tertiary-text-font-size	font	0.8125rem
--avonni-avatar-tertiary-text-font-style	font	normal
--avonni-avatar-tertiary-text-font-weight	font	400
--avonni-avatar-tertiary-text-font-family	font	—
--avonni-avatar-tertiary-text-line-height	dimension	—
--avonni-avatar-tertiary-text-letter-spacing	dimension	—
--avonni-avatar-initials-text-color	color	#ffffff
--avonni-avatar-initials-text-font-style	font	normal
--avonni-avatar-initials-text-font-weight	font	400
--avonni-avatar-initials-text-color-hover	color	#ffffff
--avonni-avatar-initials-text-font-style-hover	font	normal
--avonni-avatar-initials-text-font-weight-hover	font	400
--avonni-avatar-entity-color-border	color	transparent
--avonni-avatar-entity-fallback-icon-color-background	color	—
--avonni-avatar-entity-fallback-icon-color-foreground	color	—
--avonni-avatar-entity-fallback-icon-color-foreground-default	color	—
--avonni-avatar-entity-image-object-fit	string	—
--avonni-avatar-entity-initials-text-color	color	#ffffff
--avonni-avatar-entity-initials-text-font-style	font	normal
--avonni-avatar-entity-initials-text-font-weight	font	400
--avonni-avatar-entity-initials-text-color-hover	color	#ffffff
--avonni-avatar-entity-initials-text-font-style-hover	font	normal
--avonni-avatar-entity-initials-text-font-weight-hover	font	400
--avonni-avatar-entity-radius-border	dimension	0
--avonni-avatar-entity-sizing-border	sizing	0
--avonni-avatar-entity-styling-border	styling	none
--avonni-avatar-presence-color-border	color	#ffffff
--avonni-avatar-presence-radius-border	dimension	50%
--avonni-avatar-presence-away-color-background	color	#ff9a3c
--avonni-avatar-presence-blocked-color-background	color	#ecebea
--avonni-avatar-presence-busy-color-background	color	#bf0201
--avonni-avatar-presence-focus-color-background	color	#1589ee
--avonni-avatar-presence-offline-color-background	color	#3e3e3c
--avonni-avatar-presence-online-color-background	color	#04844b
--avonni-avatar-status-color-border	color	#ffffff
--avonni-avatar-status-radius-border	dimension	50%
--avonni-avatar-status-approved-color-background	color	#04844b
--avonni-avatar-status-declined-color-background	color	#c23934
--avonni-avatar-status-locked-color-background	color	#ecebea
--avonni-avatar-status-unknown-color-background	color	#706e6b
--avonni-avatar-fallback-icon-color-background	color	—
--avonni-avatar-fallback-icon-color-foreground	color	—
--avonni-avatar-fallback-icon-color-foreground-default	color	—
--avonni-avatar-action-button-color-background	color	#ffffff
--avonni-avatar-action-button-color-border	color	#ffffff
--avonni-avatar-action-button-color-foreground	color	#706e6b
--avonni-avatar-action-button-radius-border	dimension	30px

Key Considerations

• Accessibility: alternative-text is required and read by screen readers.
• Fallbacks: When src fails to load, the component falls back to initials, then to fallback-icon-name.
• Tertiary text: Only renders at size x-large and above.
• Actions: A single action shows as a button icon; two or more collapse into a button menu.
• Best Practice: Always set alternative-text for accessibility. Provide fallback-icon-name so the avatar degrades gracefully when an image is missing.

---

Troubleshooting Common Issues

• Image not showing: Verify src is reachable and alternative-text is set; the component falls back to initials or the icon if the image fails.
• Initials background is wrong color: The background color comes from fallback-icon-name—set a standard or custom category icon.
• Action click not firing: Confirm actions is a non-empty array and the onactionclick handler is wired in the template.
• If issues persist: Contact our support team at [email protected] for assistance.