# 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="https://3626461507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbhApDTL7kHrXte2TTtjs%2Fuploads%2Fgit-blob-86be4fd9639141b3e6371ae276dea5737129e51a%2Favatar_hero_image.jpg?alt=media" 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="image">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="text">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="https://3626461507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbhApDTL7kHrXte2TTtjs%2Fuploads%2Fgit-blob-83d465ac9f700251a7e9564b67464892000d8cfc%2Favatar_shapes.jpg?alt=media" 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](https://docs.digia.tech/ui-building-blocks/widgets/default-properties "mention").

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