Import
from reflex_ui import avatar
Description
Displays a user’s profile picture, initials, or fallback icon in a circular container. Automatically handles image loading states with a fallback.
High-Level API
avatar(
src="/path/to/image.jpg"
)
Props
URL of the image to display
Custom component to render as avatar root
Image Props
Called when image loading status changes. Receives status as ‘loading’, ‘loaded’, or ‘error’
Fallback Props
Delay in milliseconds before showing fallback content
Compositional API
For full control, use the subcomponents:
avatar.root()
Root container for the avatar.
avatar.image()
Image element displayed in the avatar. Renders an <img> element.
Loading status change handler
avatar.fallback()
Displayed when image fails to load or while loading.
Milliseconds to wait before showing fallback
Custom fallback component
Class Names
Access default class names via avatar.class_names:
ROOT: Circular container with flex centeringIMAGE: Full-size image with object-coverFALLBACK: Fallback container with pulse animation
Examples
Basic Avatar
import reflex as rx
from reflex_ui import avatar
def user_avatar():
return avatar(
src="https://example.com/avatar.jpg"
)
Avatar with Initials Fallback
import reflex as rx
from reflex_ui import avatar
def user_avatar_with_initials():
return avatar.root(
avatar.image(
src="https://example.com/avatar.jpg"
),
avatar.fallback(
rx.text("JD", weight="bold")
),
class_name="size-10"
)
Avatar with Icon Fallback
import reflex as rx
from reflex_ui import avatar
from reflex_ui.components.icons.hugeicon import hi
def user_avatar_with_icon():
return avatar.root(
avatar.image(
src="https://example.com/avatar.jpg"
),
avatar.fallback(
hi("UserIcon", size=20),
delay=100
)
)
Custom Sized Avatar
import reflex as rx
from reflex_ui import avatar
def large_avatar():
return avatar(
src="https://example.com/avatar.jpg",
class_name="size-16" # Custom size
)
Avatar Group
import reflex as rx
from reflex_ui import avatar
def avatar_group():
return rx.box(
avatar(src="https://example.com/user1.jpg"),
avatar(src="https://example.com/user2.jpg"),
avatar(src="https://example.com/user3.jpg"),
display="flex",
gap="2"
)
Loading States
The avatar automatically handles three loading states:
- Loading: While the image is being fetched
- Loaded: When the image successfully loads
- Error: When the image fails to load (shows fallback)
import reflex as rx
from reflex_ui import avatar
class AvatarState(rx.State):
loading_status: str = "loading"
def handle_status_change(self, status: str):
self.loading_status = status
def monitored_avatar():
return rx.box(
avatar.root(
avatar.image(
src="https://example.com/avatar.jpg",
on_loading_status_change=AvatarState.handle_status_change
),
avatar.fallback(
rx.text("?"),
delay=500
)
),
rx.text(f"Status: {AvatarState.loading_status}")
)