Avatar

The Avatar widget is perfect for representing users with images or initials.

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.

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.

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.

---

Properties

The Avatar's properties are grouped by function.

Content

These properties define the primary image and the fallback text.

Property	Description
Image	The image to display in the avatar. This uses the complete Image widget, giving you access to all its properties (Source, Fit, Error Image, etc.). See the Image documentation for all options.
Text	The fallback text to display if the image is not available. This uses the complete Text widget, giving you access to all its properties (Value, Text Style, etc.). See the Text documentation for all options.

Shape & Styling

These properties control the avatar's container.

Property	Description
Shape	Defines the avatar's geometric shape. Options are Circle for round avatars or Square for rectangular avatars.
Background Color	The background color of the avatar, visible behind transparent images or as the background for the fallback text.
Radius	Controls the size of the avatar when Shape is set to Circle.
Side	Controls the size of the avatar by setting the side length in pixels when Shape is set to Square.
Corner Radius	Rounds the corners of the avatar when Shape is set to Square.

Choose between Circle and Square shapes to match your design.

---

Default Properties

The Avatar widget supports the Layout and Interactions sections of the Default Properties. This allows you to control alignment, add spacing (padding/margin), and make the avatar clickable with an onClick action.

---

Best Practices

• Dynamic Content & Initials: Bind the Image source to your user data (e.g., ${user.profilePicUrl}). For the text fallback, you will need to compute the user's initials on your own and bind the result using an expression. For example, you could use a function like ${getInitials(user.fullName)} and bind it to the Text property of the nested Text widget.

• Contrast is Key: When using the text fallback, ensure the Text Color (from the Text properties) has sufficient contrast with the avatar's Background Color to be easily readable.

• Consistent Sizing: Use the same Radius or Side value for all avatars in a list to maintain a clean and uniform UI.