# Avatar

The **Avatar widget** is used to represent users or entities, typically displaying profile pictures or initials. It provides a flexible way to show either image content or text within different shape containers, making it perfect for user profiles, contact lists, and user identification throughout your application.

{% embed url="<https://www.youtube.com/watch?v=8K3p972GeIw>" %}

Watch this on Youtube: <https://www.youtube.com/watch?v=8K3p972GeIw>

#### Adding an Avatar Widget

The Avatar widget is located in the **Base Elements** section of the Widget Palette. Once added, you can configure its properties from the **Widget Properties Panel**.

<figure><img src="/files/4LKtr0p3x4jC122LEtqe" alt="A hero image showing different styles of the Avatar widget, including image and text fallbacks."><figcaption><p>The Avatar widget is perfect for representing users with images or initials.</p></figcaption></figure>

### Core Concept: Content Fallback

The Avatar widget is designed to be robust. It will always attempt to display an **Image** first. If the image source is not provided, is null, or fails to load, the widget will automatically fall back to displaying the **Text** content (typically user initials). This ensures your UI always shows a meaningful representation of the user.

{% hint style="info" %}
**Previewing Content in the Builder:** The properties panel includes a **`Preview State`** toggle. This is a design-time tool only; it has no effect on your running app. Use it to switch the view on the canvas between the `Image` and `Text` content while you are designing.
{% endhint %}

***

### Properties

The Avatar's properties are grouped by function.

#### Content

These properties define the primary image and the fallback text.

<table><thead><tr><th width="176.25390625">Property</th><th>Description</th></tr></thead><tbody><tr><td><code>Image</code></td><td>The image to display in the avatar. This uses the complete <strong>Image widget</strong>, giving you access to all its properties (Source, Fit, Error Image, etc.). See the <a href="/pages/6z7S1aQEXfxif5PYzak3">Image documentation</a> for all options.</td></tr><tr><td><code>Text</code></td><td>The fallback text to display if the image is not available. This uses the complete <strong>Text widget</strong>, giving you access to all its properties (Value, Text Style, etc.). See the <a href="/pages/KG0SqVV5TzxUrLTT0yJO">Text documentation</a> for all options.</td></tr></tbody></table>

#### Shape & Styling

These properties control the avatar's container.

<table><thead><tr><th width="176.25390625">Property</th><th>Description</th></tr></thead><tbody><tr><td><code>Shape</code></td><td>Defines the avatar's geometric shape. Options are <code>Circle</code> for round avatars or <code>Square</code> for rectangular avatars.</td></tr><tr><td><code>Background Color</code></td><td>The background color of the avatar, visible behind transparent images or as the background for the fallback text.</td></tr><tr><td><code>Radius</code></td><td>Controls the size of the avatar when <code>Shape</code> is set to <strong>Circle</strong>.</td></tr><tr><td><code>Side</code></td><td>Controls the size of the avatar by setting the side length in pixels when <code>Shape</code> is set to <strong>Square</strong>.</td></tr><tr><td><code>Corner Radius</code></td><td>Rounds the corners of the avatar when <code>Shape</code> is set to <strong>Square</strong>.</td></tr></tbody></table>

<figure><img src="/files/nkKY3YEYrkJsCX0DKQKI" alt="An illustration of the Circle and Square shapes for the Avatar widget."><figcaption><p>Choose between <code>Circle</code> and <code>Square</code> shapes to match your design.</p></figcaption></figure>

***

### Default Properties

The Avatar widget supports the **Layout** and **Interactions** sections of the [Default Properties](/ui-building-blocks/widgets/default-properties.md).

### Use Cases

You’ll typically use **Avatar** for:

* **User Identity**
  * Show the signed-in user’s photo in the header or navigation bar
  * Display avatars in chat lists, comments, reviews, or activity feeds
  * Represent participants in groups, teams, or meetings
* **Fallback Initials / Icons**
  * Show user initials when no profile picture is available
  * Use generic icons for anonymous users or system accounts
* **Lists & Cards**
  * Lead visual in contact lists, member lists, or user cards
  * Compact identity marker next to names, roles, or handles
* **Brand / Entity Representation**
  * Small logo for a brand, company, or organization
  * Represent stores, merchants, or communities in lists


---

# Agent Instructions: 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:

```
GET https://docs.digia.tech/ui-building-blocks/widgets/content-display-widgets/avatar.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.