Avatar

Download this notebook from GitHub (right-click to download).

---

import panel as pn
import panel_material_ui as pmui

pn.extension()

The Avatar component displays profile pictures, user initials, or icons in a compact, circular or square format. Avatars are commonly used throughout user interfaces to represent users, brands, or entities in a visually consistent manner.

Avatars are versatile components that can be used in various contexts:

• User profiles and account displays

• Comment sections and social feeds

• Team member listings

• Navigation bars and headers

• Contact lists and directories

• Interactive user selection interfaces

The component supports multiple content types including images, text initials, and icons, with automatic fallback handling when images fail to load. Avatars can also be made interactive with click event handling.

Parameters:

For details on other options for customizing the component see the customization guides.

Core

• clicks (int): The number of times the avatar has been clicked (read-only). Default is 0.

• object (str): The content to display - can be an image URL/path, text initials, or icon name

Display

• alt_text (str): Alternative text for screen readers and when images fail to load

• color (str): Background color for text and icon avatars - supports CSS color values

• size (str): Size of the avatar - options include ‘small’, ‘medium’ (default), and ‘large’

• variant (str): Shape variant - either ‘rounded’ (default with rounded corners) or ‘square’

Styling

• sx (dict): Component level styling API for advanced customization

• theme_config (dict): Theming API for consistent design system integration

Constructor Arguments

• on_click (callable): A Python callback to be triggered when the avatar is clicked

• js_on_click (str): JavaScript code to be triggered when the avatar is clicked

Methods

• on_click (callable): Registers a Python callback to be executed when the Avatar is clicked

• js_on_click (callable): Allows defining JavaScript callbacks with args and code to be triggered when the Avatar is clicked

---

Basic Usage

Create a simple image avatar by providing an image URL or local path:

image_avatar = pmui.Avatar(
    "https://mui.com/static/images/avatar/1.jpg",
    alt_text="User Profile"
)
image_avatar

Create text-based avatars using initials or short text:

The avatar content can be dynamically updated:

image_avatar.object = "https://mui.com/static/images/avatar/2.jpg"

Let’s reset it back:

image_avatar.object = "https://mui.com/static/images/avatar/1.jpg"

Sizes

The Avatar component supports different sizes to fit various layout requirements:

pmui.Row(
    pmui.Avatar("https://mui.com/static/images/avatar/1.jpg", size="small", margin=10),
    pmui.Avatar("https://mui.com/static/images/avatar/1.jpg", size="medium", margin=10),
    pmui.Avatar("https://mui.com/static/images/avatar/1.jpg", size="large", margin=10),
)

Variants

The Avatar component offers different shape variants:

• Rounded: Default style with rounded corners for a softer appearance

• Square: Sharp corners for a more geometric look

pmui.Row(
    pmui.Avatar("https://mui.com/static/images/avatar/1.jpg", variant="rounded", margin=10),
    pmui.Avatar("https://mui.com/static/images/avatar/1.jpg", variant="square", margin=10),
)

Text Based Avatars

You can also define text based avatars

pmui.Row(
    pmui.Avatar("P", variant="rounded", margin=10),
    pmui.Avatar("R", variant="square", margin=10),
)

Colors

Customize avatar background colors for text and icon avatars to match your design system or indicate different user types:

pmui.FlexBox(
    pmui.Avatar("A", color="#f44336", margin=10),  # Red
    pmui.Avatar("B", color="#2196f3", margin=10),  # Blue  
    pmui.Avatar("C", color="#4caf50", margin=10),  # Green
    pmui.Avatar("D", color="#ff9800", margin=10),  # Orange
)

Handling Clicks

The Avatar component supports click events through the clicks parameter and on_click method. This makes avatars interactive and useful for user profile actions or navigation.

clickable_avatar = pmui.Avatar("JD", color="#2196f3", variant="square")
click_display = pmui.Typography(f"Clicks: {clickable_avatar.clicks}", variant="body2")

# Update display when avatar is clicked
pn.bind(lambda event: click_display.param.update(object=f"Clicks: {clickable_avatar.clicks}"), clickable_avatar.param.clicks, watch=True)

pmui.Row(clickable_avatar, click_display)

You can also use the on_click method to register a callback function:

profile_avatar = pmui.Avatar("https://mui.com/static/images/avatar/2.jpg", alt_text="Profile")
status_text = pmui.Typography("Click the avatar to view profile", variant="body2")

def handle_profile_click(event):
    status_text.object = f"Profile clicked! Total clicks: {profile_avatar.clicks}"

profile_avatar.on_click(handle_profile_click)

pmui.Row(profile_avatar, status_text)

JavaScript Callbacks

For client-side interactions, you can use the js_on_click method to register JavaScript callbacks:

javascript_code = """
alert('Avatar clicked! This is a client-side JavaScript callback.');
"""

js_avatar = pmui.Avatar("JS", color="#ff5722", variant="square")
js_avatar.js_on_click(code=javascript_code)

pmui.Column(
    pmui.Typography("Click the avatar below to trigger a JavaScript alert:", variant="body2"),
    js_avatar
)

Fallback Handling

Avatars automatically handle fallbacks when images fail to load. The component will attempt to display alternative content based on the alt_text parameter:

# This will fallback gracefully since the image URL is broken
fallback_avatar = pmui.Avatar(
    object="https://broken-image-url.jpg",
    alt_text="John Doe"
)
fallback_avatar

Loading

loading_avatar = pmui.Avatar(
    "https://mui.com/static/images/avatar/1.jpg",
    loading=True
)
loading_avatar

Example: Interactive Avatar Grid

Here’s a practical example showing clickable avatars in a user selection interface:

users = [
    {"name": "Alice", "initials": "AL", "color": "#e91e63"},
    {"name": "Bob", "initials": "BO", "color": "#2196f3"},
    {"name": "Charlie", "initials": "CH", "color": "#4caf50"},
    {"name": "Diana", "initials": "DI", "color": "#ff9800"},
]

selected_user = pmui.Typography("Select a user by clicking their avatar", variant="h6")

def create_user_avatar(user):
    avatar = pmui.Avatar(user["initials"], color=user["color"], size="large", margin=5)
    
    def handle_user_click(event):
        selected_user.object = f"Selected: {user['name']} (clicked {avatar.clicks} times)"
    
    avatar.on_click(handle_user_click)
    return avatar

avatar_grid = pmui.Row(*[create_user_avatar(user) for user in users])

pmui.Column(
    pmui.Typography("User Selection", variant="h5"),
    avatar_grid,
    selected_user,
    width=600
)

Example: User Profile Card

Here’s a practical example showing how to use avatars in a user profile context with reactive updates:

import param
import panel as pn
import panel_material_ui as pmui

pn.extension()

class UserProfile(param.Parameterized):
    user_name = param.String(default="John Doe")
    profile_image = param.String(default="https://mui.com/static/images/avatar/1.jpg")
    avatar_size = param.Selector(objects=["small", "medium", "large"], default="medium")
    avatar_variant = param.Selector(objects=["rounded", "square"], default="rounded")
    
    def create_profile_card(self):
        avatar = pmui.Avatar(
            object=self.param.profile_image,
            alt_text=self.param.user_name,
            size=self.param.avatar_size,
            variant=self.param.avatar_variant
        )
        
        name_text = pmui.Typography(
            object=self.param.user_name,
            variant="h6"
        )
        
        return pmui.Card(
            pmui.Row(
                avatar,
                pmui.Column(
                    name_text,
                    pmui.Typography(object="Software Developer", variant="body2"),
                    margin=(0, 20)
                ),
                margin=20
            ),
            width=300, collapsible=False,
        )

profile = UserProfile()

# Control panel for dynamic updates
controls = pn.Param(
    profile,
    parameters=['user_name', 'avatar_size', 'avatar_variant'],
    widgets={
        'user_name': pmui.widgets.TextInput,
        'avatar_size': pmui.widgets.RadioButtonGroup,
        'avatar_variant': pmui.widgets.RadioButtonGroup
    },
    width=300
)

pn.Row(profile.create_profile_card(), controls)

API Reference

pmui.Avatar("https://mui.com/static/images/avatar/1.jpg").api(jslink=True)

References

Panel Documentation:

• How-to guides on interactivity - Learn how to add interactivity to your applications using components

• Setting up callbacks and links - Connect parameters between components and create reactive interfaces

• Declarative UIs with Param - Build parameter-driven applications

Material UI Avatar:

• Material UI Avatar Reference - Complete documentation for the underlying Material UI component

• Material UI Avatar API - Detailed API reference and configuration options

---

Download this notebook from GitHub (right-click to download).