Avatar

The Avatar component displays user profile images with intelligent fallbacks. When no image is provided, it shows user initials or a placeholder icon. The component supports various sizes and can be grouped together for team displays.

Import

use gpui_component::avatar::{Avatar, AvatarGroup};

Usage

Basic Avatar

// Avatar with image
Avatar::new()
    .src("https://example.com/avatar.jpg")
    .name("John Doe")

Avatar with Fallback Text

When no image source is provided, the Avatar displays user initials with an automatically generated color background:

// Shows "JD" initials with colored background
Avatar::new()
    .name("John Doe")

// Shows "JS" initials
Avatar::new()
    .name("Jane Smith")

Avatar Placeholder

For anonymous users or when no name is provided:

use gpui_component::IconName;

// Default user icon placeholder
Avatar::new()

// Custom placeholder icon
Avatar::new()
    .placeholder(IconName::Building2)

Avatar Sizes

Avatar::new()
    .name("John Doe")
    .xsmall()

Avatar::new()
    .name("John Doe")
    .small()

Avatar::new()
    .name("John Doe")   // 48px (default medium)

Avatar::new()
    .name("John Doe")
    .large()

// Custom size
Avatar::new()
    .name("John Doe")
    .with_size(px(100.))

Custom Styling

Avatar::new()
    .src("https://example.com/avatar.jpg")
    .with_size(px(100.))
    .border_3()
    .border_color(cx.theme().foreground)
    .shadow_sm()
    .rounded(px(20.))  // Custom border radius

AvatarGroup

Display multiple avatars in a compact, overlapping layout:

Basic Group

AvatarGroup::new()
    .child(Avatar::new().src("https://example.com/user1.jpg"))
    .child(Avatar::new().src("https://example.com/user2.jpg"))
    .child(Avatar::new().src("https://example.com/user3.jpg"))
    .child(Avatar::new().name("John Doe"))

Group with Limit

AvatarGroup::new()
    .limit(3)  // Show maximum 3 avatars
    .child(Avatar::new().src("https://example.com/user1.jpg"))
    .child(Avatar::new().src("https://example.com/user2.jpg"))
    .child(Avatar::new().src("https://example.com/user3.jpg"))
    .child(Avatar::new().src("https://example.com/user4.jpg"))  // Hidden
    .child(Avatar::new().src("https://example.com/user5.jpg"))  // Hidden

Group with Ellipsis

Show an ellipsis indicator when avatars are hidden due to the limit:

AvatarGroup::new()
    .limit(3)
    .ellipsis()  // Shows "..." when limit is exceeded
    .child(Avatar::new().src("https://example.com/user1.jpg"))
    .child(Avatar::new().src("https://example.com/user2.jpg"))
    .child(Avatar::new().src("https://example.com/user3.jpg"))
    .child(Avatar::new().src("https://example.com/user4.jpg"))
    .child(Avatar::new().src("https://example.com/user5.jpg"))

Group Sizes

// Extra small group
AvatarGroup::new()
    .xsmall()
    .child(Avatar::new().name("A"))
    .child(Avatar::new().name("B"))
    .child(Avatar::new().name("C"))

// Small group
AvatarGroup::new()
    .small()
    .child(Avatar::new().name("A"))
    .child(Avatar::new().name("B"))

// Medium group (default)
AvatarGroup::new()
    .child(Avatar::new().name("A"))
    .child(Avatar::new().name("B"))

// Large group
AvatarGroup::new()
    .large()
    .child(Avatar::new().name("A"))
    .child(Avatar::new().name("B"))

Adding Multiple Avatars

let avatars = vec![
    Avatar::new().src("https://example.com/user1.jpg"),
    Avatar::new().src("https://example.com/user2.jpg"),
    Avatar::new().name("John Doe"),
];

AvatarGroup::new()
    .children(avatars)
    .limit(5)
    .ellipsis()

API Reference

Avatar

Method	Description
new()	Create a new avatar
src(source)	Set image source (ImageSource)
name(name)	Set user name (used for initials fallback)
placeholder(icon)	Set placeholder icon (default: User icon)

Avatar Sizes (via Sizable trait)

Method	Description
xsmall()	20px avatar
small()	24px avatar
medium()	48px avatar (default)
large()	80px avatar
with_size(pixels)	Custom size in pixels

AvatarGroup

Method	Description
new()	Create a new avatar group
child(avatar)	Add single avatar to group
children(avatars)	Add multiple avatars to group
limit(count)	Maximum avatars to display (default: 3)
ellipsis()	Show "..." when limit exceeded

AvatarGroup Sizes (via Sizable trait)

Method	Description
xsmall()	Group of 20px avatars
small()	Group of 24px avatars
medium()	Group of 48px avatars (default)
large()	Group of 80px avatars
with_size(size)	Custom size for all avatars

Examples

Team Display

use gpui_component::{h_flex, v_flex};

v_flex()
    .gap_4()
    .child("Development Team")
    .child(
        AvatarGroup::new()
            .limit(4)
            .ellipsis()
            .child(Avatar::new().name("Alice Johnson").src("https://example.com/alice.jpg"))
            .child(Avatar::new().name("Bob Smith").src("https://example.com/bob.jpg"))
            .child(Avatar::new().name("Charlie Brown"))
            .child(Avatar::new().name("Diana Prince"))
            .child(Avatar::new().name("Eve Wilson"))
    )

User Profile Header

h_flex()
    .items_center()
    .gap_4()
    .child(
        Avatar::new()
            .src("https://example.com/profile.jpg")
            .name("John Doe")
            .large()
            .border_2()
            .border_color(cx.theme().primary)
    )
    .child(
        v_flex()
            .child("John Doe")
            .child("Software Engineer")
    )

Anonymous User

use gpui_component::IconName;

Avatar::new()
    .placeholder(IconName::UserCircle)
    .medium()

Avatar with Custom Colors

// The avatar automatically generates colors based on the name
// Different names will get different colors from the color palette
Avatar::new().name("Alice")    // Gets one color
Avatar::new().name("Bob")      // Gets a different color
Avatar::new().name("Charlie")  // Gets another color

Accessibility

Avatar

• Images include appropriate alt text derived from the user's name
• Fallback initials provide text content for screen readers
• Color contrast meets WCAG guidelines for text on colored backgrounds
• Placeholder icons are properly labeled

AvatarGroup

• Each avatar maintains individual accessibility properties
• Group semantics indicate collection of user avatars
• Ellipsis indicator announces hidden avatar count to screen readers
• Keyboard navigation respects individual avatar focus states

Color Generation

• Avatar background colors are generated deterministically from user names
• Colors provide sufficient contrast with white text
• Color system supports users with color vision differences

Implementation Notes

Text Initials Extraction

The component automatically extracts initials from names:

• Two words: "John Doe" → "JD"
• Multiple words: "John Smith Doe" → "JS" (first two words)
• Single word: "Superman" → "SU" (first two characters)
• All initials are converted to uppercase

Color Generation

• Uses a hash of the user's name to determine color
• Rotates through a palette of 24 distinct hues
• Applies consistent opacity for background colors
• Ensures good contrast with white text

Image Loading

• Gracefully handles failed image loads by falling back to initials
• Supports all GPUI ImageSource types (URLs, local files, etc.)
• Images are automatically sized and cropped to fit the avatar circle

Performance

• AvatarGroup efficiently renders only visible avatars
• Color calculations are cached per name
• Image loading is handled by GPUI's built-in optimization