Avatar

A versatile avatar component inspired by Family.co, supporting remote images, local images, initials, status indicators, and badges.

Import

import PrettyUI

Basic Usage

The simplest way to create an avatar is with a URL string:

// Remote image URL
PAvatar("https://example.com/avatar.jpg")

// With name fallback (shows initials if image fails)
PAvatar("https://example.com/avatar.jpg", name: "John Doe")

// Initials only
PAvatar(name: "John Doe")

// Local image
PAvatar(image: Image("profile"))

Sizes

Five sizes are available:

HStack(spacing: 16) {
    PAvatar(name: "JD").size(.xs)  // 24pt
    PAvatar(name: "JD").size(.sm)  // 32pt
    PAvatar(name: "JD").size(.md)  // 40pt (default)
    PAvatar(name: "JD").size(.lg)  // 56pt
    PAvatar(name: "JD").size(.xl)  // 72pt
}

Shapes

Choose between circular and rounded square shapes:

HStack(spacing: 24) {
    PAvatar(name: "Circle").size(.lg).shape(.circle)
    PAvatar(name: "Rounded").size(.lg).shape(.rounded)
}

Status Indicators

Show online presence with status indicators:

HStack(spacing: 16) {
    PAvatar(name: "Online").size(.lg).status(.online)   // Green
    PAvatar(name: "Away").size(.lg).status(.away)       // Yellow
    PAvatar(name: "DND").size(.lg).status(.dnd)         // Red
    PAvatar(name: "Offline").size(.lg).status(.offline) // Gray
}

Custom Status Color

PAvatar(name: "Custom")
    .size(.lg)
    .status(.custom(Color.purple))

Notification Badge

Add a badge to show notification counts:

HStack(spacing: 24) {
    PAvatar(name: "User").size(.lg).badge(count: 3)
    PAvatar(name: "User").size(.lg).badge(count: 99)
    PAvatar(name: "User").size(.lg).badge(count: 150) // Shows "99+"
}

Custom Badge Color

PAvatar(name: "User")
    .size(.lg)
    .badge(count: 5, color: .blue)

Icon Badge

Add an icon overlay badge at various positions:

// Bottom trailing (default)
PAvatar(name: "User")
    .size(.lg)
    .iconBadge("checkmark.circle.fill")

// Custom position and colors
PAvatar(name: "User")
    .size(.lg)
    .iconBadge(
        "star.fill",
        position: .topTrailing,
        iconColor: .yellow,
        backgroundColor: .orange
    )

Badge Positions

Border Ring

Add a border around the avatar:

// Default border
PAvatar(name: "User").size(.lg).bordered()

// Custom border
PAvatar(name: "User")
    .size(.lg)
    .bordered(true, color: .blue, width: 3)

Custom Colors

Override the background and foreground colors for initials:

HStack(spacing: 16) {
    PAvatar(name: "AB")
        .size(.lg)
        .background(Color.blue.opacity(0.2))
        .foreground(.blue)
    
    PAvatar(name: "CD")
        .size(.lg)
        .background(Color.green.opacity(0.2))
        .foreground(.green)
    
    PAvatar(name: "EF")
        .size(.lg)
        .background(Color.purple.opacity(0.2))
        .foreground(.purple)
}

Avatar Groups

Display overlapping avatars with PAvatarGroup:

PAvatarGroup(maxVisible: 4, size: .md) {
    PAvatar(name: "John Doe")
    PAvatar(name: "Jane Smith")
    PAvatar(name: "Bob Wilson")
    PAvatar(name: "Alice Brown")
    PAvatar(name: "Charlie Davis")
}

When there are more avatars than maxVisible, a "+N" badge appears showing the overflow count.

Group Parameters

PAvatarGroup(
    maxVisible: 3,    // Max avatars to show
    size: .lg,        // Size of avatars
    spacing: -12      // Overlap amount (negative for overlap)
) {
    // avatars...
}

Placeholder States

When no image or name is provided, a person icon is shown:

// Shows person icon
PAvatar(url: nil).size(.lg)

// Shows custom placeholder text
PAvatar(url: nil, placeholder: "?").size(.lg)

Real-World Examples

User Profile Card

HStack(spacing: 16) {
    PAvatar("https://example.com/user.jpg", name: "Sarah Connor")
        .size(.lg)
        .status(.online)
    
    VStack(alignment: .leading, spacing: 4) {
        Text("Sarah Connor")
            .font(.headline)
        Text("Product Designer")
            .font(.subheadline)
            .foregroundColor(.secondary)
    }
}

Team Members

VStack(alignment: .leading, spacing: 12) {
    Text("Team Members")
        .font(.headline)
    
    PAvatarGroup(maxVisible: 5, size: .sm) {
        PAvatar(name: "Alice")
        PAvatar(name: "Bob")
        PAvatar(name: "Charlie")
        PAvatar(name: "Diana")
        PAvatar(name: "Eve")
        PAvatar(name: "Frank")
    }
}

Contact with Verified Badge

PAvatar(name: "Verified User")
    .size(.xl)
    .iconBadge(
        "checkmark.seal.fill",
        position: .bottomTrailing,
        iconColor: .white,
        backgroundColor: .blue
    )

API Reference

PAvatar Initializers

// URL string (simplest)
PAvatar(_ urlString: String, placeholder: String? = nil)

// URL with name fallback
PAvatar(_ urlString: String, name: String)

// URL object
PAvatar(url: URL?, placeholder: String? = nil)
PAvatar(url: URL?, name: String)

// Local image
PAvatar(image: Image)

// Name only (shows initials)
PAvatar(name: String)

Modifiers

Enums

PAvatarSize

• .xs — 24pt
• .sm — 32pt
• .md — 40pt (default)
• .lg — 56pt
• .xl — 72pt

PAvatarShape

• .circle — Circular (default)
• .rounded — Rounded square

PAvatarStatus

• .online — Green indicator
• .offline — Gray indicator
• .away — Yellow indicator
• .dnd — Red indicator
• .custom(Color) — Custom color
• .none — No indicator

PAvatarBadgePosition

• .topLeading, .top, .topTrailing
• .leading, .center, .trailing
• .bottomLeading, .bottom, .bottomTrailing