Skip to main content
The Avatar component displays a user’s profile picture with automatic fallback support. It renders an image with a fallback state when the image fails to load or no image is provided.

​
Basic Usage

import reflex_ui as ui

ui.avatar(src="https://example.com/avatar.jpg")

​
With Fallback Content

ui.avatar(
    src="https://example.com/avatar.jpg",
    delay=300  # Wait 300ms before showing fallback
)

​
Component Structure

The avatar component consists of three parts:

​
Avatar Root

The main container for the avatar: 
ui.avatar.root(
    ui.avatar.image(src="https://example.com/avatar.jpg"),
    ui.avatar.fallback("JD"),
)

​
Avatar Image

Displays the user’s profile image: 
ui.avatar.image(
    src="https://example.com/avatar.jpg",
    on_loading_status_change=lambda status: rx.toast(f"Status: {status}")
)

​
Avatar Fallback

Shown when the image fails to load: 
ui.avatar.fallback(
    "JD",  # User initials
    delay=300  # Delay in milliseconds
)

​
Props Reference

​
Root Props

​
src
str
The image source URL (high-level API)
​
class_name
str
Additional CSS classes for styling

​
Image Props

​
src
str
required
The image source URL
​
on_loading_status_change
EventHandler
Callback when loading status changes. Receives the status string as parameter.

​
Fallback Props

​
delay
int
default:"0"
How long to wait before showing the fallback. Specified in milliseconds.

​
Styling

The avatar uses these default classes from reflex_ui/components/base/avatar.py:14-16:
  • Root: shrink-0 inline-flex size-6 items-center justify-center overflow-hidden rounded-full bg-secondary-1 align-middle text-base font-medium text-secondary-12 select-none
  • Image: size-full object-cover shrink-0
  • Fallback: flex size-full items-center justify-center text-sm animate-pulse bg-secondary-6

​
Implementation Details

From source code at reflex_ui/components/base/avatar.py:87-111:
  • High-level API automatically creates root, image, and fallback components
  • Image props are passed to the image component
  • Fallback props control the fallback behavior
  • Renders with proper accessibility attributes via data-slot properties

Build docs developers (and LLMs) love

Get started for freeTalk to us