> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/lwc-components/core-components/avatar.md).

# 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.

```html
<!-- 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.

```html
<!-- 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>
```

```js
// 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`  | Presence title to be shown as a tooltip on hover over the presence icon.                                                                                                                                                                                                                                                                                                                  | String                | `"bottom-right"` |          |
| `presence-title`     | Position of the presence icon. Valid values include top-left, top-right, bottom-left and bottom-right.                                                                                                                                                                                                                                                                                    | 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.                        |

### Styling Hooks

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.avonnicomponents.com/lwc-components/core-components/avatar.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.