Avatar

An easily stylable avatar component that displays a user's profile picture, initials, or fallback icon.

❯buridan add avatar

Component Guide

Use the following to build the Avatar component.

from components.ui.avatar import avatar

avatar.root(
    avatar.image(),
    avatar.fallback(),
)

Source Code & Dependencies

For manual installation, copy each of the source codes below in their respective locations.

components/core/core.py

components/ui/avatar.py

Examples

Basic

A basic avatar with an image and a fallback. The fallback is shown automatically if the image fails to load.

Props used: src on avatar.image; no props required on avatar.fallback.

import reflex as rx

from components.ui.avatar import avatar


def avatar_basic() -> rx.Component:
    fallback_id = "avatar-basic-fallback"

    return avatar.root(
        avatar.image(
            src="https://github.com/LineIndent.png",
            fallback_id=fallback_id,
            custom_attrs={"alt": "@lineindent"},
        ),
        avatar.fallback(
            "AH",
            fallback_id=fallback_id,
        ),
    )

Badge

Use avatar.badge to add a badge to the avatar. It's positioned at the bottom right by default.

Props used: none required — pass content as children.

import reflex as rx

from components.ui.avatar import avatar


def avatar_with_badge() -> rx.Component:
    fallback_id = "avatar-badge-fallback"

    return avatar.root(
        avatar.image(
            src="https://avatars.githubusercontent.com/u/84860195?v=4",
            fallback_id=fallback_id,
            custom_attrs={"alt": "@LineIndent"},
        ),
        avatar.fallback(
            "AH",
            fallback_id=fallback_id,
        ),
        avatar.badge(
            class_name="bg-green-600 dark:bg-green-800",
        ),
    )

Use class_name to customize the badge's colors, size, etc.

avatar.badge(class_name="bg-green-600 dark:bg-green-800")

Badge with Icon

You can also render an icon inside avatar.badge.

Props used: none required — pass an icon as a child.

import reflex as rx

from components.core.hugeicon import hi
from components.ui.avatar import avatar


def avatar_badge_icon() -> rx.Component:
    fallback_id = "avatar-badge-icon-fallback"

    return avatar.root(
        avatar.image(
            src="https://avatars.githubusercontent.com/u/104714959?s=200&v=4",
            fallback_id=fallback_id,
            custom_attrs={"alt": "Reflex Dev"},
        ),
        avatar.fallback(
            "RD",
            fallback_id=fallback_id,
        ),
        avatar.badge(
            hi("PlusSignIcon"),
        ),
    )

Avatar Group

Use avatar.group to render a group of overlapping avatars.

Props used: none required on avatar.group — wraps multiple avatar.root children.

import reflex as rx

from components.ui.avatar import avatar


def avatar_as_group() -> rx.Component:

    return avatar.group(
        avatar.root(
            avatar.image(
                src="/avatars/01.png",
                custom_attrs={"alt": "@avatar-1"},
            ),
            avatar.fallback("RD"),
        ),
        avatar.root(
            avatar.image(
                src="/avatars/02.png",
                custom_attrs={"alt": "@avatar-2"},
            ),
            avatar.fallback("LI"),
        ),
        avatar.root(
            avatar.image(
                src="/avatars/10.png",
                custom_attrs={"alt": "@avatar-10"},
            ),
            avatar.fallback("AH"),
        ),
        class_name="grayscale",
    )

Avatar Group Count

Use avatar.group_count to show a "+N" count at the end of a group.

Props used: none required — pass the count text as a child.

import reflex as rx

from components.ui.avatar import avatar


def avatar_with_group_count() -> rx.Component:
    return avatar.group(
        avatar.root(
            avatar.image(
                src="/avatars/10.png",
                alt="@avatar-10",
            ),
            avatar.fallback("AH"),
        ),
        avatar.root(
            avatar.image(
                src="/avatars/01.png",
                alt="@avatar-1",
            ),
            avatar.fallback("RD"),
        ),
        avatar.root(
            avatar.image(
                src="/avatars/02.png",
                alt="@avatar-2",
            ),
            avatar.fallback("LI"),
        ),
        avatar.group_count("+3"),
        class_name="grayscale",
    )

Avatar Group with Icon

You can also render an icon inside avatar.group_count.

Props used: none required — pass an icon as a child.

import reflex as rx

from components.core.hugeicon import hi
from components.ui.avatar import avatar


def avatar_group_count_icon() -> rx.Component:
    return avatar.group(
        avatar.root(
            avatar.image(
                src="https://doesnotexist.com",
                alt="@none-dev",
            ),
            avatar.fallback("AH"),
        ),
        avatar.root(
            avatar.image(
                src="https://avatars.githubusercontent.com/u/104714959?s=200&v=4",
                alt="@reflex-dev",
            ),
            avatar.fallback("CN"),
        ),
        avatar.root(
            avatar.image(
                src="https://avatars.githubusercontent.com/u/84860195?v=4",
                alt="LineIndent",
            ),
            avatar.fallback("LI"),
        ),
        avatar.group_count(
            hi("PlusSignIcon"),
        ),
        class_name="grayscale",
    )

Sizes

Use the size prop to change the avatar's size.

Props used: size on avatar.root.

import reflex as rx

from components.ui.avatar import avatar


def avatar_sizes() -> rx.Component:
    return rx.el.div(
        avatar.root(
            avatar.image(
                src="https://avatars.githubusercontent.com/u/84860195?v=4",
                alt="@LineIndent",
            ),
            avatar.fallback("LI"),
            size="sm",
        ),
        avatar.root(
            avatar.image(
                src="https://avatars.githubusercontent.com/u/84860195?v=4",
                alt="@LineIndent",
            ),
            avatar.fallback("LI"),
        ),
        avatar.root(
            avatar.image(
                src="https://avatars.githubusercontent.com/u/84860195?v=4",
                alt="@LineIndent",
            ),
            avatar.fallback("LI"),
            size="lg",
        ),
        class_name="flex flex-wrap items-center gap-2",
    )

avatar.root can be used as a trigger for a dropdown menu.

Props used: size on avatar.root; see the Menu docs for menu-specific props.

import reflex as rx

from components.ui.avatar import avatar
from components.ui.button import button
from components.ui.menu import menu


def avatar_dropdown_menu() -> rx.Component:
    return menu.root(
        menu.trigger(
            rx.el.img(
                src="https://github.com/LineIndent.png",
                alt="lineindent",
                class_name=avatar.class_names.IMAGE,
            ),
            class_name=avatar.class_names.ROOT,
        ),
        menu.content(
            menu.item("Profile"),
            menu.item("Billing"),
            menu.item("Settings"),
        ),
    )

API Reference

avatar.root

The root component that wraps the avatar image and fallback.

avatar.root(
    avatar.image(src="/avatars/01.png"),
    avatar.fallback("RD"),
)

Prop	Type	Default
`size`	`Literal["default", "sm", "lg", "xl"]`	`"default"`
`class_name`	`str`	`""`

avatar.image

Renders the <img> and probes its src client-side on mount — if it fails to load, it hides itself and reveals the sibling avatar.fallback automatically. No fallback_id wiring needed.

avatar.image(src="/avatars/01.png", custom_attrs={"alt": "@shadcn"})

Prop	Type	Default
`src`	`str`
`id`	`str`	auto-generated
`class_name`	`str`	`""`

Any other prop accepted by a native <img> is also passed straight through.

avatar.fallback

Shown automatically when avatar.image fails to load.

avatar.fallback("RD")

Prop	Type	Default
`class_name`	`str`	`""`

avatar.badge

Displays a badge indicator on the avatar, positioned at the bottom right by default.

avatar.badge(hi("BadgeCheck01Icon"))

Prop	Type	Default
`class_name`	`str`	`""`

avatar.group

Displays a group of avatars with overlapping styling.

avatar.group(
    avatar.root(...),
    avatar.root(...),
)

Prop	Type	Default
`class_name`	`str`	`""`

avatar.group_count

Displays a count indicator at the end of an avatar group.

avatar.group_count("+3")

Prop	Type	Default
`class_name`	`str`	`""`