> 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/dynamic-components/components/avatar.md).

# Avatar

The Avonni Avatar component displays a visual representation of a person, group, or entity — using an image, initials, or an icon fallback — with optional detail text, tags, status and presence indicators, an entity overlay, and action buttons.

## Overview

Use the Avatar to give records a recognizable identity in lists, cards, headers, and dashboards. It renders an image when one is available and falls back to initials or a Lightning icon when it isn't. Most settings accept either a static value or a value mapped dynamically to a record field, so the same avatar adapts to whatever record it represents.

## Configuration

To configure the Avatar, select it on the canvas. The **Edit Avatar** panel opens on the right with three tabs: **Properties**, **Interactions**, and **Style**. The sections below mirror the Properties tab, in panel order.

### Content

The Content section controls what renders inside the avatar frame and how it is shaped and sized.

* **Icon Name** — The Lightning Design System icon used as a fallback when no image is available or the image fails to load. It also drives the background color used behind initials. Type an icon API name such as `standard:contact` or `standard:account`.
* **Initials** — Letters shown when no image is available. For a two-word name, use the first capitalized letter of each word; for a single-word name, use its first two letters (one capital, one lowercase).
* **Initials Auto Formatted** — When enabled, the initials are derived automatically: the first letter of each word for multi-word values, or the first two letters of a single word. *Requires: the **Initials** field to be set.*
* **Image Source** — The image to display. Click **Select Image** to upload one, paste a static URL (for example a Static Resource), or use the **Mapped** option to bind it to a record field at runtime so each avatar shows its own record's image.
* **URL** — An optional web address the avatar links to when clicked.
* **Target** — Where the linked URL opens: **Self** (current tab, default), **Blank** (new tab), **Parent**, or **Top**. *Requires: the **URL** field to be set.*
* **Variant** — The shape of the avatar frame: **Circle** or **Square** (default). Use Circle for people and Square for companies or object-based entities.
* **Size** — How large the avatar renders: **X-Small**, **Small**, **Medium** (default), **Large**, **X-Large**, **Xx-Large**, or **Xxx-Large**.
* **Icon Position** — Where the fallback icon sits within the frame: **Start**, **Center** (default), or **End**.
* **Alternative Text** — Descriptive text for the avatar, surfaced as hover text and read by screen readers.

**Mapping the image to a record:**

Click the **Mapped** button next to the Image Source field to bind it to a data source at runtime. Two sources are available:

* [**Record variable**](/dynamic-components/component-builder/resources/variable.md) — Select a record variable you've created in the Dynamic Components app, then pick the field that contains the image URL (e.g., `Profile_Photo_URL__c` on a Contact record). Each avatar renders the image from its own record's data.
* **`$component` attribute** — If you've set a [**Target Page Object**](/dynamic-components/core-concepts/target-page-object.md) at the component level, the `$component` attribute exposes that object's fields. Map the Image Source to the relevant image field, and the avatar resolves the URL from the current page context automatically.

<figure><img src="/files/WkhvDUmJJg2jBOL1vfli" alt=""><figcaption></figcaption></figure>

*This illustration shows how to map the avatar image to the current record owner by selecting the User object through the* [***Target Page Object***](/dynamic-components/core-concepts/target-page-object.md) *setup, then choosing the image URL field configured on that object using the `$Component` global variable.*

### Details

The Details section adds text and tags alongside the avatar. Each text field accepts a static value or a value mapped dynamically to a record field.

* **Hide Details** — Hides the primary, secondary, and tertiary text.
* **Primary Text** — The main label, usually the person's name (e.g., `Contact.Name`).
* **Secondary Text** — A smaller supporting line, usually a role or subtitle (e.g., `Contact.Title`).
* **Tertiary Text** — An additional line, usually a status message. *Requires: the **Size** to be `X-Large` or `Xx-Large`.*
* **Text Position** — Where the text block sits relative to the avatar: **Right** (default), **Left**, or **Center**.
* **Tags** — Small pill-shaped labels for categorization. For each tag, set a **Label** and a **Variant** (Base, Brand, Inverse, Alt-Inverse, Success, Info, Warning, Error, or Offline).

### Status

The Status section overlays a small colored dot to communicate a record's current business state.

1. In the **Type** dropdown, select the state to display: **Approved**, **Locked**, **Declined**, or **Unknown**.
2. Set the **Position** — which corner the dot appears in: **Top Left**, **Top Right** (default), **Bottom Left**, or **Bottom Right**. *Requires: a **Type** to be selected.*

**Advanced options:**

* **Title** — A short text label associated with the status dot, shown as a tooltip on hover. *Requires: a **Type** to be selected.*

Both **Type** and **Title** accept a static value or can be mapped dynamically — for example, mapping **Type** to a record field so the dot updates automatically based on the record's current state.

### Presence

The Presence section overlays a small colored dot to indicate a person's availability. Status and Presence can both appear on the same avatar at once.

1. In the **Type** dropdown, select the availability state: **Online**, **Busy**, **Focus**, **Offline**, **Blocked**, or **Away**.
2. Set the **Position** — which corner the dot appears in: **Top Left**, **Top Right**, **Bottom Left**, or **Bottom Right** (default). *Requires: a **Type** to be selected.*

**Advanced options:**

* **Title** — A short text label associated with the presence dot, shown as a tooltip on hover. *Requires: a **Type** to be selected.*

Both **Type** and **Title** accept a static value or can be mapped dynamically — for example, mapping **Type** to a record field so the dot updates automatically based on the person's current availability.

> **Status vs. Presence** — Use Status for business states tied to a record (approval, stage, task progress). Use Presence for a person's real-time availability. Both dots can display at the same time.

### Entity

The Entity section adds a small secondary icon or image badge in a corner of the avatar to clarify what type of entity is represented — useful when a list mixes individuals, teams, and companies. It looks like a small badge overlaid on the avatar corner, similar to a company logo on a profile photo.

* **Icon Name** — A Lightning Design System icon API name for the badge (e.g., `standard:groups` for a team, `standard:account` for a company).
* **Initials** — Letters to show in the badge when no image is available, using the first capitalized letter of each word.
* **Image Source** — An image URL for the badge. Click **Select Image** to upload one or map it dynamically.
* **Variant** — The badge shape: **Circle** or **Square** (default).
* **Position** — Which corner the badge appears in: **Top Left** (default), **Top Right**, **Bottom Left**, or **Bottom Right**.
* **Title** — Tooltip text shown on hover over the entity badge.

### Actions

The Actions section adds interactive buttons to the avatar. A single action renders as an icon button; two or more actions render in a button menu.

1. Add one or more actions. For each, set a **Label** (button text), a **Name** (a unique identifier used by interactions), and an optional **Icon Name**.
2. Set the **Position** — where the action button or menu sits relative to the avatar: **Bottom Left** (default), **Bottom Right**, **Top Left**, or **Top Right**.
3. Optionally set an **Icon Name** for the menu to replace the default down-arrow icon shown when multiple actions are present.

Once your actions are created, open the [**Interactions Panel**](/dynamic-components/component-builder/interactions.md) and use the **On Action Click** trigger to define what happens when a user clicks each button.

### Set Component Visibility

All components support conditional visibility — see [Component Visibility](/dynamic-components/core-concepts/component-visibility.md).

## Use Cases

* **Contact lists** — Circle avatar with Primary Text mapped to `Contact.Name`, Secondary Text to `Contact.Title`, and a Presence dot mapped to an availability field.
* **Account records** — Square avatar with the image mapped to a logo URL field, an entity badge set to `standard:account`, and a Status dot mapped to a rating field.
* **Support queues** — Agent avatars with Presence indicators and a "Message" action button.
* **Team dashboards** — An avatar grid with name, role, and skill tags all mapped to User record fields.

## Interactions

[Interactions](/dynamic-components/component-builder/interactions.md) define what happens when users interact with the Avatar. Configure them from the **Interactions** tab of the Edit Avatar panel.

### Click

Fires when a user clicks the avatar itself. Use it to navigate to a record, open a modal, or trigger any behavior defined in your flow.

### Action Click

Fires when a user clicks one of the action buttons or menu items configured in the Actions section. Use the **targetName** output to identify which action was clicked and scope your flow logic to that specific action.

## Styling

The Avatar offers extensive styling options on the **Style** tab of the Edit Avatar panel.

{% tabs %}
{% tab title="Margin" %}
Controls the *outer* spacing around the avatar.

* **Top / Right / Bottom / Left:** Adjust the space on each side of the avatar.
  {% endtab %}

{% tab title="Padding" %}
Controls the *inner* spacing inside the avatar container.

* **Top / Right / Bottom / Left:** Adjust the inner spacing on each side.
  {% endtab %}

{% tab title="Border" %}
Customizes the border surrounding the avatar container.

* **Color:** Set the border color.
* **Size:** Adjust the border thickness.
* **Style:** Choose a border style (solid, dashed, dotted, etc.).
* **Radius:** Round the corners of the border.
  {% endtab %}

{% tab title="Horizontal Alignment" %}

* **Horizontal Alignment:** Align the avatar within its container.
  {% endtab %}

{% tab title="Avatar Border" %}
Styles the border drawn around the avatar image itself.

* **Color / Size / Style / Radius:** Customize the avatar's image border.
  {% endtab %}

{% tab title="Avatar" %}

* **Background Color / Foreground Color:** Set the fallback icon colors.
* **Image Object Fit:** Control how the avatar image fills its area.
  {% endtab %}

{% tab title="Primary Text" %}

* **Color:** Set the primary text color.
* **Font Size / Font Style / Font Weight:** Control the primary text typography.
  {% endtab %}

{% tab title="Secondary Text" %}

* **Color:** Set the secondary text color.
* **Font Size / Font Style / Font Weight:** Control the secondary text typography.
  {% endtab %}

{% tab title="Tertiary Text" %}

* **Color:** Set the tertiary text color.
* **Font Size / Font Style / Font Weight:** Control the tertiary text typography.
  {% endtab %}

{% tab title="Action" %}

* **Background Color / Foreground Color:** Set the action button colors.
* **Border Color / Border Radius:** Style the action button border.
  {% endtab %}

{% tab title="Initials" %}

* **Color / Color Hover:** Set the initials color and hover color.
* **Font Style / Font Weight:** Control the initials typography.
  {% endtab %}

{% tab title="Entity" %}

* **Border Radius / Border Color / Border Style / Border Size:** Customize the entity badge border.
* **Background Color / Foreground Color:** Set the entity fallback icon colors.
* **Image Object Fit:** Control how the entity image fills its area.
* **Initials Color / Initials Font Style / Initials Font Weight:** Style the entity initials.
  {% endtab %}

{% tab title="Presence" %}

* **Border Color / Border Radius:** Customize the presence dot border.
* **Background per state:** Set the background color for Away, Blocked, Busy, Focus, Offline, and Online.
  {% endtab %}

{% tab title="Status" %}

* **Border Color / Border Radius:** Customize the status dot border.
* **Background per state:** Set the background color for Approved, Declined, Locked, and Unknown.
  {% endtab %}
  {% endtabs %}

## Output Variables

The Avatar exposes this output variable you can reference elsewhere on the page after the user interacts with it.

### Action Click

Updates when a user clicks one of the avatar's action buttons or menu items.

| Output variable         | Type          | What it returns                                                                                         |
| ----------------------- | ------------- | ------------------------------------------------------------------------------------------------------- |
| **Clicked Action Name** | Text (String) | The name of the action button the user clicked, matching the **Name** field set in the Actions section. |

> **Example:** When a user clicks a "Message" action on an agent avatar, use **Clicked Action Name** to check that the value is `message` and then open a messaging flow for that agent.

## Troubleshooting Common Issues

* **Image not rendering** — Image URLs must be publicly accessible or hosted within Salesforce (Static Resources or Salesforce Files with public sharing). Private or authenticated URLs will not render.
* **Fallback not showing the expected image** — If a mapped image is empty for a given record, the avatar falls back to initials or the icon set in Icon Name. Verify the mapped field contains a valid URL for that record.
* **Tertiary Text not showing** — Tertiary text only renders at the X-Large and Xx-Large sizes. Increase the Size setting to see it.
* **Screen reader not describing the avatar** — Fill in the Alternative Text field so screen readers can describe the avatar to assistive technology users.
* **Inconsistent appearance across a list** — Use the same Variant and Size for avatars of the same type across your app (e.g., all contact avatars as circles at Medium size) to maintain visual consistency.


---

# 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/dynamic-components/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.