syncfusion-maui-avatar-view

어떤 스킬인가요?

Implements Syncfusion .NET MAUI Avatar View (SfAvatarView) for displaying user profile pictures, initials, or group avatars. Use when working with avatar views, profile pictures, user images, initials display, profile icons, or contact images. Ideal for implementing user profile displays, contact lists, chat interfaces, or social feeds.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

# BadgeView Integration with Avatar View

The .NET MAUI SfAvatarView integrates seamlessly with SfBadgeView to display notifications, status indicators, and counts on avatars. This guide covers complete BadgeView integration patterns.

## Overview

BadgeView adds contextual information to avatars:
- **Status indicators** - Online, away, busy, offline
- **Notification counts** - Unread messages, alerts
- **Activity badges** - New content, updates
- **Custom indicators** - Any icon or text

## When to Use Badge Integration

- **Messaging apps** - Show online status or unread message counts
- **Social networks** - Indicate new notifications or friend requests
- **Collaboration tools** - Display presence or activity status
- **Contact lists** - Show availability or verification badges
- **Any scenario** requiring contextual avatar information

## Basic BadgeView Setup

### Prerequisites

BadgeView is included in the same `Syncfusion.Maui.Core` package as AvatarView. No additional installation required.

### Namespace Import

```xaml
xmlns:badge="clr-namespace:Syncfusion.Maui.Core;assembly=Syncfusion.Maui.Core"
xmlns:sfavatar="clr-namespace:Syncfusion.Maui.Core;assembly=Syncfusion.Maui.Core"
```

### Basic Structure

The avatar goes inside the `BadgeView.Content`, and badge configuration goes in `BadgeView.BadgeSettings`:

```xaml
<badge:SfBadgeView>
    <badge:SfBadgeView.Content>
        <sfavatar:SfAvatarView ... />
    </badge:SfBadgeView.Content>
    <badge:SfBadgeView.BadgeSettings>
        <badge:BadgeSettings ... />
    </badge:SfBadgeView.BadgeSettings>
</badge:SfBadgeView>
```

## Status Badge Example

Display online/offline status with a colored badge.

**XAML:**
```xaml
<badge:SfBadgeView HorizontalOptions="Center"
                   VerticalOptions="Center">
    <badge:SfBadgeView.Content>
        <sfavatar:SfAvatarView 
            ContentType="Custom"
            ImageSource="user_profile.png"
            WidthRequest="60"
            HeightRequest="60"
            CornerRadius="30"
            Stroke="Black"
            StrokeThickness="1" />
    </badge:SfBadgeView.Content>
    <badge:SfBadgeView.BadgeSettings>
        <badge:BadgeSettings 
            Type="Success"
            Icon="Available"
            Position="BottomRight"
            Offset="-10,-10"
            Animation="Scale" />
    </badge:SfBadgeView.BadgeSettings>
</badge:SfBadgeView>
```

**C#:**
```csharp
using Syncfusion.Maui.Core;

var badgeView = new SfBadgeView
{
    HorizontalOptions = LayoutOptions.Center,
    VerticalOptions = LayoutOptions.Center
};

var avatarView = new SfAvatarView
{
    ContentType = ContentType.Custom,
    ImageSource = "user_profile.png",
    WidthRequest = 60,
    HeightRequest = 60,
    CornerRadius = 30,
    Stroke = Colors.Black,
    StrokeThickness = 1
};

var badgeSettings = new BadgeSettings
{
    Type = BadgeType.Success,
    Icon = BadgeIcon.Available,
    Position = BadgePosition.BottomRight,
    Offset = new Point(-10, -10),
    Animation = BadgeAnimation.Scale
};

badgeView.Content = avatarView;
badgeView.BadgeSettings = badgeSettings;
```

**Result:** Avatar with green "available" indicator at bottom-right.

## Badge Types

BadgeView supports multiple types with predefined colors:

| Type | Color | Common Use |
|------|-------|------------|
| **Success** | Green | Online, available, verified |
| **Warning** | Orange | Away, idle, warning |
| **Error** | Red | Offline, error, busy |
| **Info** | Blue | Information, notifications |
| **Primary** | Purple | Default, custom |
| **Secondary** | Gray | Inactive, secondary status |
| **Light** | Light Gray | Subtle indicators |
| **Dark** | Dark Gray | High contrast |

### Type Examples

**Success (Online):**
```xaml
<badge:BadgeSettings 
    Type="Success"
    Icon="Available"
    Position="BottomRight" />
```

**Warning (Away):**
```xaml
<badge:BadgeSettings 
    Type="Warning"
    Icon="Away"
    Position="BottomRight" />
```

**Error (Busy):**
```xaml
<badge:BadgeSettings 
    Type="Error"
    Icon="Busy"
    Position="BottomRight" />
```

## Badge Icons

Common icons for avatar badges:

- **Available** - Green checkmark or dot (online)
- **Away** - Clock or moon (away)
- **Busy** - Do not disturb symbol
- **Offline** - X or empty (offline)
- **None** - No icon (text or count only)

### Icon Implementation

```xaml
<badge:BadgeSettings 
    Icon="Available"
    Type="Success"
    Position="BottomRight" />
```

```csharp
badgeSettings.Icon = BadgeIcon.Available;
badgeSettings.Type = BadgeType.Success;
```

## Badge Positioning

Position badges at any corner or edge of the avatar:

### Position Options

- **TopLeft**
- **TopRight**
- **BottomLeft**
- **BottomRight** (most common for status)

### Position Examples

**Top Right (Notification Count):**
```xaml
<badge:SfBadgeView HorizontalOptions="Center"
    VerticalOptions="Center" BadgeText="5">
    <badge:SfBadgeView.Content>
        ...
    </badge:SfBadgeView.Content>
    <badge:SfBadgeView.BadgeSettings>
        <badge:BadgeSettings 
            Type="Error"
            Position="TopRight"
            Offset="-5,-5" />
    </badge:SfBadgeView.BadgeSettings>
</badge:SfBadgeView>
```

**Bottom Right (Status):**
```xaml
<badge:BadgeSettings 
    Type="Success"
    Icon="Available"
    Position="BottomRight"
    Offset="-10,-10" />
```

**Bottom Left:**
```xaml
<badge:BadgeSettings 
    Type="Primary"
    Icon="Available"
    Position="BottomLeft"
    Offset="10,-10" />
```

## Badge Offset

The `Offset` property fine-tunes badge placement using X,Y coordinates:

```xaml
<!-- Move badge 10px left and 10px up from corner -->
<badge:BadgeSettings Offset="-10,-10" />

<!-- Move badge 5px right and 5px down from corner -->
<badge:BadgeSettings Offset="5,5" />
```

**Guidelines:**
- Negative X: Move left
- Positive X: Move right
- Negative Y: Move up
- Positive Y: Move down

**Typical offsets:**
- Small avatars (40-60px): `Offset="-5,-5"`
- Medium avatars (60-80px): `Offset="-10,-10"`
- Large avatars (80px+): `Offset="-12,-12"`

## Notification Count Badge

Display unread message or notification counts.

**XAML:**
```xaml
<badge:SfBadgeView HorizontalOptions="Center"
                   VerticalOptions="Center"
                   BadgeText="12">
    <badge:SfBadgeView.Content>
        <sfavatar:SfAvatarView 
            ContentType="Initials"
            AvatarName="John Doe"
            InitialsType="DoubleCharacter"
            AvatarShape="Circle"
            AvatarSize="Large"
            Background="CornflowerBlue"
            InitialsColor="White" />
    </badge:SfBadgeView.Content>
    <badge:SfBadgeView.BadgeSettings>
        <badge:BadgeSettings 
            Type="Error"
            Position="TopRight"
            Offset="-8,-8"
            Animation="None" />
    </badge:SfBadgeView.BadgeSettings>
</badge:SfBadgeView>
```

**C#:**
```csharp
 var badgeView = new SfBadgeView { BadgeText = "12" };

 var avatar = new SfAvatarView
 {
     ContentType = ContentType.Initials,
     AvatarName = "John Doe",
     InitialsType = InitialsType.DoubleCharacter,
     AvatarShape = AvatarShape.Circle,
     AvatarSize = AvatarSize.Large,
     Background = Colors.CornflowerBlue,
     InitialsColor = Colors.White
 };
 var badgeSettings = new BadgeSettings
 {
     Type = BadgeType.Error,
     Position = BadgePosition.TopRight,
     Offset = new Point(-8, -8),
     Animation = BadgeAnimation.None
 };

 badgeView.Content = avatar;
 badgeView.BadgeSettings = badgeSettings;
```

**Dynamic count updates:**
```csharp
public void UpdateNotificationCount(SfBadgeView badgeView, int count)
{
    if (count > 0)
    {
        badgeView.BadgeText = count > 99 ? "99+" : count.ToString();
        badgeView.BadgeSettings.Type = BadgeType.Error;
    }
    else
    {
        badgeView.BadgeText = string.Empty;
    }
}
```

## Badge Animations

Add visual emphasis when badges appear or change:

### Animation Types

- **None** - No animation (instant)
- **Scale** - Badge scales up when appearing (recommended)

### Animation Examples

**Scale (Default):**
```xaml
<badge:BadgeSettings Animation="Scale" />
```

**No Animation:**
```xaml
<badge:BadgeSettings Animation="None" />
```

**Best practices:**
- Use `Scale` for status changes
- Use `None` for static badges

## Common Badge Patterns

### Pattern 1: Online Status Indicator

```csharp
public SfBadgeView CreateOnlineAvatar(string userName, bool isOnline)
{
    var badgeView = new SfBadgeView();
    
    var avatar = new SfAvatarView
    {
        ContentType = ContentType.Initials,
        AvatarName = userName,
        InitialsType = InitialsType.DoubleCharacter,
        AvatarShape = AvatarShape.Circle,
        AvatarSize = AvatarSize.Medium,
        AvatarColorMode = AvatarColorMode.DarkBackground
    };
    
    var badgeSettings = new BadgeSettings
    {
        Type = isOnline ? BadgeType.Success : BadgeType.Secondary,
        Icon = isOnline ? BadgeIcon.Available : BadgeIcon.Away,
        Position = BadgePosition.BottomRight,
        Offset = new Point(-10, -10),
        Animation = BadgeAnimation.Scale
    };
    
    badgeView.Content = avatar;
    badgeView.BadgeSettings = badgeSettings;
    
    return badgeView;
}
```

### Pattern 2: Message Count Badge

```csharp
public SfBadgeView CreateMessageAvatar(string imagePath, int unreadCount)
{
    var badgeView = new SfBadgeView();
    
    var avatar = new SfAvatarView
    {
        ContentType = ContentType.Custom,
        ImageSource = imagePath,
        AvatarShape = AvatarShape.Circle,
        AvatarSize = AvatarSize.Large
    };
    
    var badgeSettings = new BadgeSettings
    {
        Position = BadgePosition.TopRight,
        Offset = new Point(-5, -5)
    };
    
    if (unreadCount > 0)
    {
        badgeSettings.Type = BadgeType.Error;
        badgeView.BadgeText = unreadCount > 99 ? "99+" : unreadCount.ToString();
        badgeSettings.Animation = BadgeAnimation.Scale;
    }
    
    badgeView.Content = avatar;
    badgeView.BadgeSettings = badgeSettings;
    
    return badgeView;
}
```

### Pattern 3: Presence Status (Away/Busy/Available)

```csharp
public enum PresenceStatus
{
    Available,
    Away,
    Busy,
    Offline
}

public SfBadgeView CreatePresenceAvatar(string userName, PresenceStatus status)
{
    var badgeView = new SfBadgeView();
    
    var avatar = new SfAvatarView
    {
        ContentType = ContentType.Initials,
        AvatarName = userName,
        AvatarShape = AvatarShape.Circle,
        AvatarSize = AvatarSize.Medium
    };
    
    var badgeSettings = new BadgeSettings
    {
        Position = BadgePosition.BottomRight,
        Offset = new Point(-10, -10),
        Animation = BadgeAnimation.Scale
    };
    
    switch (status)
    {
        case PresenceStatus.Available:
            badgeSettings.Type = BadgeType.Success;
            badgeSettings.Icon = BadgeIcon.Available;
            break;
        case PresenceStatus.Away:
            badgeSettings.Type = BadgeType.Warning;
            badgeSettings.Icon = BadgeIcon.Away;
            break;
        case PresenceStatus.Busy:
            badgeSettings.Type = BadgeType.Error;
            badgeSettings.Icon = BadgeIcon.Busy;
            break;
        case PresenceStatus.Offline:
            badgeSettings.Type = BadgeType.Secondary;
            badgeSettings.Icon = BadgeIcon.None;
            break;
    }
    
    badgeView.Content = avatar;
    badgeView.BadgeSettings = badgeSettings;
    
    return badgeView;
}
```

### Pattern 4: Verified User Badge

```csharp
public SfBadgeView CreateVerifiedAvatar(string imagePath)
{
    var badgeView = new SfBadgeView();
    
    var avatar = new SfAvatarView
    {
        ContentType = ContentType.Custom,
        ImageSource = imagePath,
        AvatarShape = AvatarShape.Circle,
        AvatarSize = AvatarSize.Large,
        Stroke = Colors.Gold,
        StrokeThickness = 2
    };
    
    var badgeSettings = new BadgeSettings
    {
        Type = BadgeType.Info,
        Icon = BadgeIcon.Busy,  // Use appropriate verification icon
        Position = BadgePosition.BottomRight,
        Offset = new Point(-8, -8),
        Animation = BadgeAnimation.None
    };
    
    badgeView.Content = avatar;
    badgeView.BadgeSettings = badgeSettings;
    
    return badgeView;
}
```

## Complete Example: Chat List Item

```xaml
<ContentPage xmlns:badge="clr-namespace:Syncfusion.Maui.Core;assembly=Syncfusion.Maui.Core"
             xmlns:sfavatar="clr-namespace:Syncfusion.Maui.Core;assembly=Syncfusion.Maui.Core">
    
    <CollectionView ItemsSource="{Binding Contacts}">
        <CollectionView.ItemTemplate>
            <DataTemplate>
                <Grid Padding="15,10" ColumnDefinitions="Auto,*">
                    
                    <!-- Avatar with Badge -->
                    <badge:SfBadgeView Grid.Column="0" BadgeText="{Binding UnreadCount}">
                        <badge:SfBadgeView.Content>
                            <sfavatar:SfAvatarView 
                                ContentType="Custom"
                                ImageSource="{Binding ProfileImage}"
                                AvatarShape="Circle"
                                AvatarSize="Medium" />
                        </badge:SfBadgeView.Content>
                        <badge:SfBadgeView.BadgeSettings>
                            <badge:BadgeSettings 
                                Type="{Binding BadgeType}"
                                Position="TopRight"
                                Offset="-8,-8" />
                        </badge:SfBadgeView.BadgeSettings>
                    </badge:SfBadgeView>
                    
                    <!-- Contact Info -->
                    <VerticalStackLayout Grid.Column="1" Margin="15,0,0,0">
                        <Label Text="{Binding Name}" FontAttributes="Bold" />
                        <Label Text="{Binding LastMessage}" TextColor="Gray" />
                    </VerticalStackLayout>
                    
                </Grid>
            </DataTemplate>
        </CollectionView.ItemTemplate>
    </CollectionView>
    
</ContentPage>
```

## Best Practices

1. **Position consistently** - Use BottomRight for status, TopRight for counts
2. **Keep badges small** - Don't overwhelm the avatar
3. **Use appropriate colors** - Follow badge type conventions
4. **Animate status changes** - Use Scale animation for updates
5. **Handle large counts** - Show "99+" for numbers > 99
6. **Test visibility** - Ensure badges don't obscure important avatar content
7. **Respect theme** - Badge colors should work in light and dark modes

## Troubleshooting

### Issue: Badge Not Visible

**Solutions:**
- Check Offset values (negative values move badge inward)
- Verify BadgeSettings is set on BadgeView
- Ensure badge Type is specified
- Check if BadgeText or Icon is set

### Issue: Badge Positioning Wrong

**Solutions:**
- Adjust Offset property
- Try different Position values
- Account for avatar stroke thickness in offset
- Test on different screen sizes

### Issue: Badge Cuts Off

**Solutions:**
- Add margin/padding to parent container
- Reduce Offset magnitude
- Ensure avatar is not clipped by parent bounds

# Content Types in .NET MAUI Avatar View

The SfAvatarView control supports five different content types for displaying user representations. This guide covers all content types with complete implementation examples.

## Table of Contents

- [Overview](#overview)
- [Default Type](#default-type)
- [Initials Type](#initials-type)
  - [Single Character Initials](#single-character-initials)
  - [Double Character Initials](#double-character-initials)
  - [Customizing Initials Color](#customizing-initials-color)
- [Custom Image Type](#custom-image-type)
- [Avatar Character Type](#avatar-character-type)
- [Group View Type](#group-view-type)
  - [Group with Images](#group-with-images)
  - [Group with Initials](#group-with-initials)
  - [Mixed Images and Initials](#mixed-images-and-initials)
  - [Custom Colors in Groups](#custom-colors-in-groups)
- [Choosing the Right Content Type](#choosing-the-right-content-type)
- [Common Issues and Solutions](#common-issues-and-solutions)

## Overview

The `ContentType` property determines what the Avatar View displays:

| Content Type | Purpose | Use Case |
|--------------|---------|----------|
| **Default** | Built-in vector image | Placeholder during loading |
| **Initials** | Text-based representation | When images aren't available |
| **Custom** | User-provided images | Profile pictures, photos |
| **AvatarCharacter** | Preset vector avatars | Fun, uniform anonymous users |
| **Group** | Multiple users (up to 3) | Team avatars, group chats |

## Default Type

The **Default** content type displays a built-in vector image when no other content is specified.

### When to Use
- Placeholder while loading actual content
- Generic user representation
- Testing or prototyping

### Implementation

**XAML:**
```xaml
<sfavatar:SfAvatarView 
    ContentType="Default"
    Background="OrangeRed"
    WidthRequest="50"
    HeightRequest="50"
    CornerRadius="25"
    Stroke="Black"
    StrokeThickness="1"
    HorizontalOptions="Center"
    VerticalOptions="Center" />
```

**C#:**
```csharp
var avatarView = new SfAvatarView
{
    ContentType = ContentType.Default,
    Background = Colors.OrangeRed,
    WidthRequest = 50,
    HeightRequest = 50,
    CornerRadius = 25,
    Stroke = Colors.Black,
    StrokeThickness = 1,
    HorizontalOptions = LayoutOptions.Center,
    VerticalOptions = LayoutOptions.Center
};
```

### Key Points
- No additional properties required
- Displays a generic user icon
- Background color can be customized
- Respects all standard appearance properties

## Initials Type

The **Initials** content type displays text characters based on a user's name. It supports both single and double character display.

### Key Properties

- **InitialsType** - `SingleCharacter` or `DoubleCharacter`
- **AvatarName** - The name to extract initials from
- **InitialsColor** - The color of the text

### Single Character Initials

Displays the first character of the provided name.

**XAML:**
```xaml
<sfavatar:SfAvatarView 
    ContentType="Initials"
    InitialsType="SingleCharacter"
    AvatarName="Alex"
    Background="CornflowerBlue"
    InitialsColor="White"
    WidthRequest="60"
    HeightRequest="60"
    CornerRadius="30" />
```

**C#:**
```csharp
var avatarView = new SfAvatarView
{
    ContentType = ContentType.Initials,
    InitialsType = InitialsType.SingleCharacter,
    AvatarName = "Alex",
    Background = Colors.CornflowerBlue,
    InitialsColor = Colors.White,
    WidthRequest = 60,
    HeightRequest = 60,
    CornerRadius = 30
};
```

**Result:** Displays "A"

### Double Character Initials

Displays two characters based on the name:
- **Single word:** First and last letters (e.g., "Alex" → "AX")
- **Multiple words:** First letter of first and last words (e.g., "John Doe" → "JD")

**XAML:**
```xaml
<sfavatar:SfAvatarView 
    ContentType="Initials"
    InitialsType="DoubleCharacter"
    AvatarName="John Doe"
    Background="OrangeRed"
    InitialsColor="White"
    WidthRequest="60"
    HeightRequest="60"
    CornerRadius="30" />
```

**C#:**
```csharp
var avatarView = new SfAvatarView
{
    ContentType = ContentType.Initials,
    InitialsType = InitialsType.DoubleCharacter,
    AvatarName = "John Doe",
    Background = Colors.OrangeRed,
    InitialsColor = Colors.White,
    WidthRequest = 60,
    HeightRequest = 60,
    CornerRadius = 30
};
```

**Results:**
- "John Doe" → "JD"
- "Alex" → "AX"
- "Sarah Jane Smith" → "SS"

### Customizing Initials Color

**XAML:**
```xaml
<sfavatar:SfAvatarView 
    ContentType="Initials"
    InitialsType="DoubleCharacter"
    AvatarName="Sarah"
    Background="LightGray"
    InitialsColor="DarkSlateGray"
    FontSize="20"
    FontAttributes="Bold" />
```

**C#:**
```csharp
var avatarView = new SfAvatarView
{
    ContentType = ContentType.Initials,
    InitialsType = InitialsType.DoubleCharacter,
    AvatarName = "Sarah",
    Background = Colors.LightGray,
    InitialsColor = Colors.DarkSlateGray,
    FontSize = 20,
    FontAttributes = FontAttributes.Bold
};
```

## Custom Image Type

The **Custom** content type allows you to display user-provided images.

### When to Use
- User profile pictures
- Contact photos
- Any custom image content

### Implementation

**XAML:**
```xaml
<sfavatar:SfAvatarView 
    ContentType="Custom"
    ImageSource="user_profile.png"
    WidthRequest="100"
    HeightRequest="100"
    CornerRadius="50"
    Stroke="Gray"
    StrokeThickness="2" />
```

**C#:**
```csharp
var avatarView = new SfAvatarView
{
    ContentType = ContentType.Custom,
    ImageSource = "user_profile.png",
    WidthRequest = 100,
    HeightRequest = 100,
    CornerRadius = 50,
    Stroke = Colors.Gray,
    StrokeThickness = 2
};
```

### Loading Images from Different Sources

**From Resources:**
```csharp
ImageSource = "user.png"
```

**From File System:**
```csharp
ImageSource = ImageSource.FromFile("/path/to/image.png")
```

**From URI:**
```csharp
ImageSource = ImageSource.FromUri(new Uri("https://example.com/avatar.jpg"))
```

**From Stream:**
```csharp
ImageSource = ImageSource.FromStream(() => new MemoryStream(imageBytes))
```

### Best Practices
- Place images in `Resources/Images` folder for embedded resources
- Use appropriate image sizes (don't load 4K images for 100px avatars)
- Consider caching for remote images
- Provide fallback to initials if image fails to load

## Avatar Character Type

The **AvatarCharacter** content type displays preset vector images from a built-in collection.

### Available Characters

Avatar1 through Avatar32 are available as preset options.

### Implementation

**XAML:**
```xaml
<sfavatar:SfAvatarView 
    ContentType="AvatarCharacter"
    AvatarCharacter="Avatar8"
    Background="DeepSkyBlue"
    WidthRequest="50"
    HeightRequest="50"
    CornerRadius="25"
    Stroke="Black"
    StrokeThickness="1" />
```

**C#:**
```csharp
var avatarView = new SfAvatarView
{
    ContentType = ContentType.AvatarCharacter,
    AvatarCharacter = AvatarCharacter.Avatar8,
    Background = Colors.DeepSkyBlue,
    WidthRequest = 50,
    HeightRequest = 50,
    CornerRadius = 25,
    Stroke = Colors.Black,
    StrokeThickness = 1
};
```

### Use Cases
- Anonymous user representation
- Guest accounts
- Gamification (assigning characters to users)
- Consistent placeholder avatars

### Dynamic Assignment

```csharp
// Assign random avatar character
var random = new Random();
var avatarNumber = random.Next(1, 33);
var avatarCharacter = (AvatarCharacter)Enum.Parse(typeof(AvatarCharacter), $"Avatar{avatarNumber}");

var avatarView = new SfAvatarView
{
    ContentType = ContentType.AvatarCharacter,
    AvatarCharacter = avatarCharacter
};
```

## Group View Type

The **Group** content type displays up to three images or initials in a single avatar view, perfect for representing teams or groups.

### Key Properties

- **GroupSource** - Collection of items to display
- **ImageSourceMemberPath** - Property path for images
- **InitialsMemberPath** - Property path for initials
- **BackgroundColorMemberPath** - Property path for background colors
- **InitialsColorMemberPath** - Property path for initials text colors

### Data Model Setup

Create a model class for group members:

```csharp
public class Employee
{
    public string Name { get; set; }
    public string ImageSource { get; set; }
    public Color BackgroundColor { get; set; }
    public Color InitialsColor { get; set; }
}
```

Create a ViewModel:

```csharp
public class EmployeeViewModel : INotifyPropertyChanged
{
    private ObservableCollection<Employee> _collectionImage;
    
    public ObservableCollection<Employee> CollectionImage
    {
        get => _collectionImage;
        set
        {
            _collectionImage = value;
            OnPropertyChanged(nameof(CollectionImage));
        }
    }
    
    public EmployeeViewModel()
    {
        CollectionImage = new ObservableCollection<Employee>
        {
            new Employee 
            { 
                Name = "Mike", 
                ImageSource = "mike.png", 
                BackgroundColor = Colors.Gray 
            },
            new Employee 
            { 
                Name = "Alex", 
                ImageSource = "alex.png", 
                BackgroundColor = Colors.Bisque 
            },
            new Employee 
            { 
                Name = "Ellana", 
                ImageSource = "ellana.png", 
                BackgroundColor = Colors.LightCoral 
            }
        };
    }
    
    public event PropertyChangedEventHandler PropertyChanged;
    
    protected void OnPropertyChanged(string propertyName)
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }
}
```

### Group with Images

**XAML:**
```xaml
<ContentPage.BindingContext>
    <local:EmployeeViewModel />
</ContentPage.BindingContext>

<sfavatar:SfAvatarView 
    ContentType="Group"
    GroupSource="{Binding CollectionImage}"
    ImageSourceMemberPath="ImageSource"
    BackgroundColorMemberPath="BackgroundColor"
    WidthRequest="50"
    HeightRequest="50"
    CornerRadius="25"
    Stroke="Black"
    StrokeThickness="1"
    HorizontalOptions="Center"
    VerticalOptions="Center" />
```

**C#:**
```csharp
var viewModel = new EmployeeViewModel();

var avatarView = new SfAvatarView
{
    ContentType = ContentType.Group,
    GroupSource = viewModel.CollectionImage,
    ImageSourceMemberPath = "ImageSource",
    BackgroundColorMemberPath = "BackgroundColor",
    WidthRequest = 50,
    HeightRequest = 50,
    CornerRadius = 25,
    Stroke = Colors.Black,
    StrokeThickness = 1,
    BindingContext = viewModel
};
```

### Group with Initials

Display initials only (no images):

```csharp
public EmployeeViewModel()
{
    CollectionImage = new ObservableCollection<Employee>
    {
        new Employee { Name = "Mike", BackgroundColor = Colors.Gray },
        new Employee { Name = "Alex", BackgroundColor = Colors.Bisque },
        new Employee { Name = "Ellana", BackgroundColor = Colors.LightCoral }
    };
}
```

**XAML:**
```xaml
<sfavatar:SfAvatarView 
    ContentType="Group"
    GroupSource="{Binding CollectionImage}"
    InitialsMemberPath="Name"
    BackgroundColorMemberPath="BackgroundColor"
    WidthRequest="50"
    HeightRequest="50"
    CornerRadius="25"
    Stroke="Black"
    StrokeThickness="1" />
```

### Mixed Images and Initials

You can mix images and initials in the same group view:

```csharp
public EmployeeViewModel()
{
    CollectionImage = new ObservableCollection<Employee>
    {
        new Employee { ImageSource = "mike.png" },
        new Employee { Name = "Alex", BackgroundColor = Colors.White },
        new Employee { ImageSource = "ellana.png" }
    };
}
```

**XAML:**
```xaml
<sfavatar:SfAvatarView 
    ContentType="Group"
    GroupSource="{Binding CollectionImage}"
    ImageSourceMemberPath="ImageSource"
    InitialsMemberPath="Name"
    BackgroundColorMemberPath="BackgroundColor"
    WidthRequest="50"
    HeightRequest="50"
    CornerRadius="25" />
```

**Behavior:**
- If `ImageSource` is provided → displays image
- If `ImageSource` is empty/null → displays initials from `Name`

### Custom Colors in Groups

**Custom Initials Color:**
```xaml
<sfavatar:SfAvatarView 
    ContentType="Group"
    GroupSource="{Binding CollectionImage}"
    InitialsMemberPath="Name"
    InitialsColorMemberPath="InitialsColor"
    WidthRequest="50"
    HeightRequest="50"
    CornerRadius="25" />
```

**Custom Background Color:**
```xaml
<sfavatar:SfAvatarView 
    ContentType="Group"
    GroupSource="{Binding CollectionImage}"
    InitialsMemberPath="Name"
    BackgroundColorMemberPath="BackgroundColor"
    WidthRequest="50"
    HeightRequest="50"
    CornerRadius="25" />
```

## Choosing the Right Content Type

| Scenario | Recommended Type | Fallback |
|----------|------------------|----------|
| User has profile picture | Custom | Initials |
| No user image available | Initials | Default |
| Anonymous/guest users | AvatarCharacter | Default |
| Team/group representation | Group | Multiple separate avatars |
| Loading state | Default | N/A |
| Testing/prototyping | Default or AvatarCharacter | N/A |

## Common Issues and Solutions

### Issue: Initials Not Displaying

**Problem:** AvatarName is set but nothing shows

**Solutions:**
1. Verify ContentType is set to `Initials`
2. Check that AvatarName is not null or empty
3. Ensure InitialsColor contrasts with Background
4. Verify InitialsType is set

### Issue: Custom Image Not Loading

**Problem:** ContentType is Custom but image doesn't appear

**Solutions:**
1. Verify image exists in Resources/Images
2. Check ImageSource path is correct (case-sensitive)
3. Ensure ContentType is set to `Custom`
4. Check image build action is `MauiImage`

### Issue: Group View Shows Only One Item

**Problem:** GroupSource has multiple items but only one displays

**Solutions:**
1. Verify ContentType is set to `Group`
2. Check that GroupSource is an observable collection
3. Ensure member paths are correctly set
4. Verify collection has actual data

### Issue: Initials Show Wrong Characters

**Problem:** Double character shows unexpected letters

**Explanation:**
- Single word: First and last letters (not first two)
- Multiple words: First letters of first and last words

**Example:**
- "Alex" → "AX" (not "AL")
- "John Michael Doe" → "JD" (not "JM")

### Issue: Group View Performance

**Problem:** Slow rendering with large collections

**Solution:**
- Limit GroupSource to maximum 3 items (control limitation)
- Collections larger than 3 items only display first 3
- Consider using separate avatars for more than 3 users

## Advanced Patterns

### Dynamic Content Type Switching

```csharp
public void SetAvatarContent(SfAvatarView avatar, User user)
{
    if (!string.IsNullOrEmpty(user.ImageUrl))
    {
        avatar.ContentType = ContentType.Custom;
        avatar.ImageSource = ImageSource.FromUri(new Uri(user.ImageUrl));
    }
    else if (!string.IsNullOrEmpty(user.Name))
    {
        avatar.ContentType = ContentType.Initials;
        avatar.InitialsType = InitialsType.DoubleCharacter;
        avatar.AvatarName = user.Name;
        avatar.Background = GenerateColorFromName(user.Name);
    }
    else
    {
        avatar.ContentType = ContentType.Default;
        avatar.Background = Colors.Gray;
    }
}
```

### Consistent Color Generation for Initials

```csharp
public Color GenerateColorFromName(string name)
{
    var hash = name.GetHashCode();
    var random = new Random(hash);
    
    return Color.FromRgb(
        random.Next(100, 200),
        random.Next(100, 200),
        random.Next(100, 200)
    );
}
```

This ensures the same name always gets the same color, providing visual consistency.

# Customization in .NET MAUI Avatar View

The SfAvatarView control provides extensive customization options for appearance, including aspect ratios, colors, gradients, sizing, and font properties.

## Table of Contents

- [Aspect Ratio Control](#aspect-ratio-control)
- [Color Customization](#color-customization)
  - [Stroke Color](#stroke-color)
  - [Background Color](#background-color)
  - [Automatic Color Modes](#automatic-color-modes)
  - [Gradient Backgrounds](#gradient-backgrounds)
- [Sizing Properties](#sizing-properties)
  - [Width and Height](#width-and-height)
  - [Stroke Thickness](#stroke-thickness)
  - [Corner Radius](#corner-radius)
  - [Content Padding](#content-padding)
- [Font Customization](#font-customization)
  - [Font Size](#font-size)
  - [Font Family](#font-family)
  - [Font Attributes](#font-attributes)
  - [Font Auto-Scaling](#font-auto-scaling)
- [Best Practices](#best-practices)
- [Common Customization Patterns](#common-customization-patterns)

## Aspect Ratio Control

The `Aspect` property controls how images fit within the avatar view bounds. This is particularly important for Custom image content types.

### Available Aspect Modes

| Mode | Behavior | Use Case |
|------|----------|----------|
| **AspectFit** | Fits entire image, adds space if needed | Preserve full image visibility |
| **AspectFill** | Fills display, clips image while preserving aspect | Common for profile pictures |
| **Fill** | Stretches to fill display | May cause distortion, use carefully |
| **Center** | Centers image at original size | Small logos or icons |

### Implementation

**XAML:**
```xaml
<sfavatar:SfAvatarView 
    ContentType="Custom"
    ImageSource="person.png"
    Aspect="AspectFit"
    AvatarShape="Circle"
    WidthRequest="80"
    HeightRequest="80"
    StrokeThickness="1"
    Stroke="Black"
    HorizontalOptions="Center"
    VerticalOptions="Center" />
```

**C#:**
```csharp
var avatarView = new SfAvatarView
{
    ContentType = ContentType.Custom,
    ImageSource = "person.png",
    Aspect = Aspect.AspectFit,
    AvatarShape = AvatarShape.Circle,
    WidthRequest = 80,
    HeightRequest = 80,
    Stroke = Colors.Black,
    StrokeThickness = 1,
    HorizontalOptions = LayoutOptions.Center,
    VerticalOptions = LayoutOptions.Center
};
```

### Choosing the Right Aspect

**AspectFit** - Best for:
- Images with important edges (logos, icons)
- When you can't risk cropping content
- Non-square images in circular avatars

**AspectFill** (Default) - Best for:
- Profile photos
- Standard avatars
- When slight cropping is acceptable

**Fill** - Use sparingly:
- Only when aspect ratio matches exactly
- Background patterns
- Decorative elements

**Center** - Best for:
- Small icons or badges
- Images smaller than avatar size
- Precise positioning needs

## Color Customization

### Stroke Color

The `Stroke` property defines the border color around the avatar.

**XAML:**
```xaml
<sfavatar:SfAvatarView 
    ContentType="Custom"
    ImageSource="user.png"
    AvatarShape="Circle"
    AvatarSize="Large"
    Stroke="Red"
    StrokeThickness="2"
    HorizontalOptions="Center"
    VerticalOptions="Center" />
```

**C#:**
```csharp
var avatarView = new SfAvatarView
{
    ContentType = ContentType.Custom,
    ImageSource = "user.png",
    AvatarShape = AvatarShape.Circle,
    AvatarSize = AvatarSize.Large,
    Stroke = Colors.Red,
    StrokeThickness = 2,
    HorizontalOptions = LayoutOptions.Center,
    VerticalOptions = LayoutOptions.Center
};
```

**Common Stroke Colors:**
```csharp
// Subtle border
avatar.Stroke = Colors.LightGray;

// Accent color
avatar.Stroke = Color.FromArgb("#007AFF");

// Status indicators
avatar.Stroke = Colors.Green;  // Online
avatar.Stroke = Colors.Orange; // Away
avatar.Stroke = Colors.Gray;   // Offline
```

### Background Color

Set the background color using `Background` or `BackgroundColor` properties.

#### Using Background Property

**XAML:**
```xaml
<sfavatar:SfAvatarView 
    ContentType="Initials"
    AvatarName="Alex"
    AvatarShape="Circle"
    AvatarSize="Large"
    Background="Bisque"
    InitialsColor="Black"
    StrokeThickness="1"
    Stroke="Black" />
```

**C#:**
```csharp
var avatarView = new SfAvatarView
{
    ContentType = ContentType.Initials,
    AvatarName = "Alex",
    AvatarShape = AvatarShape.Circle,
    AvatarSize = AvatarSize.Large,
    Background = Colors.Bisque,
    InitialsColor = Colors.Black,
    Stroke = Colors.Black,
    StrokeThickness = 1
};
```

#### Using BackgroundColor Property

**XAML:**
```xaml
<sfavatar:SfAvatarView 
    ContentType="Initials"
    AvatarName="Alex"
    BackgroundColor="Bisque"
    InitialsColor="Black"
    AvatarColorMode="Default" />
```

**C#:**
```csharp
var avatarView = new SfAvatarView
{
    ContentType = ContentType.Initials,
    AvatarName = "Alex",
    BackgroundColor = Colors.Bisque,
    InitialsColor = Colors.Black,
    AvatarColorMode = AvatarColorMode.Default
};
```

**Note:** When using explicit background colors, set `AvatarColorMode` to `Default`.

### Automatic Color Modes

The `AvatarColorMode` property provides automatic color schemes for initials avatars.

#### Default Color Mode

Uses the explicitly set Background or BackgroundColor:

```csharp
var avatarView = new SfAvatarView
{
    ContentType = ContentType.Initials,
    AvatarName = "Sarah",
    AvatarColorMode = AvatarColorMode.Default,
    Background = Colors.Purple,
    InitialsColor = Colors.White
};
```

#### Dark Background Mode

Applies dark tones to both background and text automatically:

**XAML:**
```xaml
<sfavatar:SfAvatarView 
    ContentType="Initials"
    InitialsType="DoubleCharacter"
    AvatarName="Alex"
    AvatarShape="Circle"
    AvatarSize="Large"
    AvatarColorMode="DarkBackground"
    StrokeThickness="1"
    Stroke="Black"
    HorizontalOptions="Center"
    VerticalOptions="Center" />
```

**C#:**
```csharp
var avatarView = new SfAvatarView
{
    ContentType = ContentType.Initials,
    InitialsType = InitialsType.DoubleCharacter,
    AvatarName = "Alex",
    AvatarShape = AvatarShape.Circle,
    AvatarSize = AvatarSize.Large,
    AvatarColorMode = AvatarColorMode.DarkBackground,
    Stroke = Colors.Black,
    StrokeThickness = 1,
    HorizontalOptions = LayoutOptions.Center,
    VerticalOptions = LayoutOptions.Center
};
```

**Result:** Dark background with light text for high contrast.

#### Light Background Mode

Applies light tones to both background and text automatically:

**XAML:**
```xaml
<sfavatar:SfAvatarView 
    ContentType="Initials"
    InitialsType="DoubleCharacter"
    AvatarName="Alex"
    AvatarShape="Circle"
    AvatarSize="Large"
    AvatarColorMode="LightBackground"
    Stroke="Black"
    StrokeThickness="1"
    HorizontalOptions="Center"
    VerticalOptions="Center" />
```

**C#:**
```csharp
var avatarView = new SfAvatarView
{
    ContentType = ContentType.Initials,
    InitialsType = InitialsType.DoubleCharacter,
    AvatarName = "Alex",
    AvatarShape = AvatarShape.Circle,
    AvatarSize = AvatarSize.Large,
    AvatarColorMode = AvatarColorMode.LightBackground,
    Stroke = Colors.Black,
    StrokeThickness = 1,
    HorizontalOptions = LayoutOptions.Center,
    VerticalOptions = LayoutOptions.Center
};
```

**Result:** Light background with dark text for softer appearance.

### Gradient Backgrounds

Use `LinearGradientBrush` to create gradient backgrounds.

**XAML:**
```xaml
<sfavatar:SfAvatarView 
    ContentType="Initials"
    AvatarName="Alex"
    InitialsType="DoubleCharacter"
    AvatarShape="Circle"
    AvatarSize="Large"
    StrokeThickness="1"
    Stroke="Black"
    HorizontalOptions="Center"
    VerticalOptions="Center">
    <sfavatar:SfAvatarView.Background>
        <LinearGradientBrush StartPoint="0,0" EndPoint="1,0">
            <GradientStop Color="#2F9BDF" Offset="0"/>
            <GradientStop Color="#51F1F2" Offset="1"/>
        </LinearGradientBrush>
    </sfavatar:SfAvatarView.Background>
</sfavatar:SfAvatarView>
```

**C#:**
```csharp
var avatarView = new SfAvatarView
{
    ContentType = ContentType.Initials,
    InitialsType = InitialsType.DoubleCharacter,
    AvatarName = "Alex",
    AvatarShape = AvatarShape.Circle,
    AvatarSize = AvatarSize.Large,
    Stroke = Colors.Black,
    StrokeThickness = 1,
    Background = new LinearGradientBrush
    {
        StartPoint = new Point(0, 0),
        EndPoint = new Point(1, 0),
        GradientStops = new GradientStopCollection
        {
            new GradientStop { Color = Color.FromArgb("#2F9BDF"), Offset = 0 },
            new GradientStop { Color = Color.FromArgb("#51F1F2"), Offset = 1 }
        }
    }
};
```

#### Gradient Directions

**Horizontal (Left to Right):**
```csharp
StartPoint = new Point(0, 0)
EndPoint = new Point(1, 0)
```

**Vertical (Top to Bottom):**
```csharp
StartPoint = new Point(0, 0)
EndPoint = new Point(0, 1)
```

**Diagonal:**
```csharp
StartPoint = new Point(0, 0)
EndPoint = new Point(1, 1)
```

#### Multi-Color Gradients

```csharp
var gradientBrush = new LinearGradientBrush
{
    StartPoint = new Point(0, 0),
    EndPoint = new Point(1, 1),
    GradientStops = new GradientStopCollection
    {
        new GradientStop { Color = Color.FromArgb("#FF6B6B"), Offset = 0 },
        new GradientStop { Color = Color.FromArgb("#FFA500"), Offset = 0.5f },
        new GradientStop { Color = Color.FromArgb("#4ECDC4"), Offset = 1 }
    }
};

avatar.Background = gradientBrush;
```

## Sizing Properties

### Width and Height

Control the exact size of the avatar view:

**XAML:**
```xaml
<sfavatar:SfAvatarView 
    ContentType="Custom"
    ImageSource="user.png"
    WidthRequest="120"
    HeightRequest="120"
    CornerRadius="60" />
```

**C#:**
```csharp
var avatarView = new SfAvatarView
{
    ContentType = ContentType.Custom,
    ImageSource = "user.png",
    WidthRequest = 120,
    HeightRequest = 120,
    CornerRadius = 60
};
```

**Common Sizes:**
- Small: 40x40
- Medium: 60x60
- Large: 80x80
- Extra Large: 120x120
- Profile Page: 150x150 or larger

### Stroke Thickness

Control the width of the border:

**XAML:**
```xaml
<sfavatar:SfAvatarView 
    ContentType="Custom"
    ImageSource="user.png"
    AvatarShape="Circle"
    AvatarSize="Large"
    Stroke="Black"
    StrokeThickness="4"
    HorizontalOptions="Center"
    VerticalOptions="Center" />
```

**C#:**
```csharp
var avatarView = new SfAvatarView
{
    ContentType = ContentType.Custom,
    ImageSource = "user.png",
    AvatarShape = AvatarShape.Circle,
    AvatarSize = AvatarSize.Large,
    Stroke = Colors.Black,
    StrokeThickness = 4,
    HorizontalOptions = LayoutOptions.Center,
    VerticalOptions = LayoutOptions.Center
};
```

**Guidelines:**
- Subtle border: 1-2px
- Standard border: 2-3px
- Prominent border: 4-6px
- Avoid > 8px (becomes too dominant)

### Corner Radius

Create rounded corners or perfect circles:

**XAML:**
```xaml
<sfavatar:SfAvatarView 
    ContentType="Custom"
    ImageSource="user.png"
    WidthRequest="60"
    HeightRequest="60"
    CornerRadius="20"
    StrokeThickness="1"
    Stroke="Black"
    HorizontalOptions="Center"
    VerticalOptions="Center" />
```

**C#:**
```csharp
var avatarView = new SfAvatarView
{
    ContentType = ContentType.Custom,
    ImageSource = "user.png",
    WidthRequest = 60,
    HeightRequest = 60,
    CornerRadius = 20,
    Stroke = Colors.Black,
    StrokeThickness = 1,
    HorizontalOptions = LayoutOptions.Center,
    VerticalOptions = LayoutOptions.Center
};
```

**Common Patterns:**
- Perfect circle: CornerRadius = Width/2
- Rounded square: CornerRadius = Width/8 to Width/6
- Slight rounding: CornerRadius = 4-8
- Square: CornerRadius = 0

### Content Padding

Add spacing between the stroke and the content:

**XAML:**
```xaml
<sfavatar:SfAvatarView 
    ContentType="Custom"
    ImageSource="twitter.png"
    AvatarShape="Circle"
    Stroke="Black"
    StrokeThickness="1"
    ContentPadding="10"
    HorizontalOptions="Center"
    VerticalOptions="Center" />
```

**C#:**
```csharp
var avatarView = new SfAvatarView
{
    ContentType = ContentType.Custom,
    ImageSource = "twitter.png",
    AvatarShape = AvatarShape.Circle,
    Stroke = Colors.Black,
    StrokeThickness = 1,
    ContentPadding = 10,
    HorizontalOptions = LayoutOptions.Center,
    VerticalOptions = LayoutOptions.Center
};
```

**Use Cases:**
- Logo badges: Higher padding (8-15px)
- Standard avatars: No padding or minimal (0-4px)
- Icon avatars: Medium padding (6-10px)

## Font Customization

Font properties apply to Initials content type.

### Font Size

**XAML:**
```xaml
<sfavatar:SfAvatarView 
    ContentType="Initials"
    AvatarName="Alex"
    AvatarShape="Circle"
    FontSize="24"
    InitialsColor="White"
    Background="Navy" />
```

**C#:**
```csharp
var avatarView = new SfAvatarView
{
    ContentType = ContentType.Initials,
    AvatarName = "Alex",
    AvatarShape = AvatarShape.Circle,
    FontSize = 24,
    InitialsColor = Colors.White,
    Background = Colors.Navy
};
```

**Size Guidelines:**
- Small avatars (40-50px): FontSize 14-16
- Medium avatars (60-80px): FontSize 18-24
- Large avatars (100+px): FontSize 28-36

### Font Family

**XAML:**
```xaml
<sfavatar:SfAvatarView 
    ContentType="Initials"
    AvatarName="Alex"
    AvatarShape="Circle"
    FontFamily="OpenSansSemibold"
    InitialsColor="White"
    Background="Navy" />
```

**C#:**
```csharp
var avatarView = new SfAvatarView
{
    ContentType = ContentType.Initials,
    AvatarName = "Alex",
    AvatarShape = AvatarShape.Circle,
    FontFamily = "OpenSansSemibold",
    InitialsColor = Colors.White,
    Background = Colors.Navy
};
```

**Note:** Font must be registered in `MauiProgram.cs` or available system-wide.

### Font Attributes

**XAML:**
```xaml
<sfavatar:SfAvatarView 
    ContentType="Initials"
    AvatarName="Alex"
    AvatarShape="Circle"
    FontAttributes="Bold"
    InitialsColor="White"
    Background="Navy" />
```

**C#:**
```csharp
var avatarView = new SfAvatarView
{
    ContentType = ContentType.Initials,
    AvatarName = "Alex",
    AvatarShape = AvatarShape.Circle,
    FontAttributes = FontAttributes.Bold,
    InitialsColor = Colors.White,
    Background = Colors.Navy
};
```

**Options:**
- `FontAttributes.None` - Regular weight
- `FontAttributes.Bold` - Bold text (recommended for initials)
- `FontAttributes.Italic` - Italic text (rarely used for avatars)

### Font Auto-Scaling

Enable automatic font scaling based on OS accessibility settings:

**XAML:**
```xaml
<sfavatar:SfAvatarView 
    ContentType="Initials"
    InitialsType="DoubleCharacter"
    AvatarName="Alex"
    WidthRequest="50"
    HeightRequest="50"
    FontAttributes="Bold"
    FontAutoScalingEnabled="True"
    CornerRadius="25" />
```

**C#:**
```csharp
var avatarView = new SfAvatarView
{
    ContentType = ContentType.Initials,
    InitialsType = InitialsType.DoubleCharacter,
    AvatarName = "Alex",
    WidthRequest = 50,
    HeightRequest = 50,
    FontAttributes = FontAttributes.Bold,
    FontAutoScalingEnabled = true,
    CornerRadius = 25
};
```

**Benefits:**
- Respects user's text size preferences
- Improves accessibility
- Better user experience for visually impaired users

**Default:** `false` (maintains consistent design)

## Best Practices

### Color Accessibility

1. **Ensure sufficient contrast** between initials and background
   ```csharp
   // Good contrast
   InitialsColor = Colors.White
   Background = Colors.Navy
   
   // Poor contrast (avoid)
   InitialsColor = Colors.LightGray
   Background = Colors.White
   ```

2. **Test with different color modes**
   - Light and dark themes
   - High contrast modes
   - Color blindness simulators

### Sizing Consistency

1. **Use consistent sizes within contexts**
   ```csharp
   // Chat list
   var listAvatarSize = 40;
   
   // Chat detail
   var detailAvatarSize = 60;
   
   // Profile page
   var profileAvatarSize = 120;
   ```

2. **Maintain aspect ratios**
   - Always use square dimensions for circles
   - WidthRequest = HeightRequest for most cases

### Performance

1. **Avoid excessive customization**
   - Don't create thousands of unique gradient avatars
   - Cache commonly used configurations

2. **Optimize images**
   - Use appropriately sized source images
   - Consider image compression

3. **Limit gradient complexity**
   - Stick to 2-3 gradient stops
   - More stops = more rendering cost

## Common Customization Patterns

### Pattern 1: Elegant Profile Avatar

```csharp
var avatar = new SfAvatarView
{
    ContentType = ContentType.Custom,
    ImageSource = "profile.png",
    AvatarShape = AvatarShape.Circle,
    WidthRequest = 120,
    HeightRequest = 120,
    Stroke = Colors.LightGray,
    StrokeThickness = 3,
    Aspect = Aspect.AspectFill
};
```

### Pattern 2: Bold Initials Avatar

```csharp
var avatar = new SfAvatarView
{
    ContentType = ContentType.Initials,
    InitialsType = InitialsType.DoubleCharacter,
    AvatarName = userName,
    AvatarShape = AvatarShape.Circle,
    AvatarSize = AvatarSize.Large,
    AvatarColorMode = AvatarColorMode.DarkBackground,
    FontAttributes = FontAttributes.Bold,
    FontSize = 24
};
```

### Pattern 3: Gradient Brand Avatar

```csharp
var avatar = new SfAvatarView
{
    ContentType = ContentType.Initials,
    AvatarName = companyName,
    AvatarShape = AvatarShape.Circle,
    FontSize = 28,
    FontAttributes = FontAttributes.Bold,
    InitialsColor = Colors.White,
    Background = new LinearGradientBrush
    {
        StartPoint = new Point(0, 0),
        EndPoint = new Point(1, 1),
        GradientStops = new GradientStopCollection
        {
            new GradientStop { Color = brandColorPrimary, Offset = 0 },
            new GradientStop { Color = brandColorSecondary, Offset = 1 }
        }
    }
};
```

### Pattern 4: Subtle Icon Avatar

```csharp
var avatar = new SfAvatarView
{
    ContentType = ContentType.Custom,
    ImageSource = "icon.png",
    AvatarShape = AvatarShape.Circle,
    WidthRequest = 50,
    HeightRequest = 50,
    Background = Colors.White,
    ContentPadding = 12,
    Stroke = Color.FromArgb("#E0E0E0"),
    StrokeThickness = 1
};
```

# Getting Started with .NET MAUI Avatar View

This guide walks you through setting up and configuring the Syncfusion .NET MAUI Avatar View (SfAvatarView) in your application.

## Step 1: Create a New .NET MAUI Project

### Using Visual Studio

1. Open Visual Studio
2. Select **File → New → Project**
3. Search for "**.NET MAUI App**" template
4. Select the template and click **Next**
5. Configure your project:
   - **Name:** Your project name (e.g., "AvatarViewDemo")
   - **Location:** Choose your preferred directory
   - Click **Next**
6. Select the .NET framework version (.NET 9 or later)
7. Click **Create**

### Using CLI

```bash
dotnet new maui -n AvatarViewDemo
cd AvatarViewDemo
```

## Step 2: Install Syncfusion MAUI Core NuGet Package

### Using Visual Studio

1. In **Solution Explorer**, right-click your project
2. Select **Manage NuGet Packages**
3. Click the **Browse** tab
4. Search for **Syncfusion.Maui.Core**
5. Select the package from the results
6. Click **Install** (install the latest stable version)
7. Accept the license agreement if prompted
8. Wait for package restoration to complete

### Using Package Manager Console

```powershell
Install-Package Syncfusion.Maui.Core
```

### Using .NET CLI

```bash
dotnet add package Syncfusion.Maui.Core
```

### Verify Installation

Check your `.csproj` file to confirm the package reference:

```xml
<ItemGroup>
  <PackageReference Include="Syncfusion.Maui.Core" Version="33.1.44" />
</ItemGroup>
```

## Step 3: Register the Syncfusion Handler

The Syncfusion.Maui.Core package requires handler registration in your `MauiProgram.cs` file.

### Open MauiProgram.cs

Locate the file in your project root.

### Add Using Directive

At the top of the file, add:

```csharp
using Syncfusion.Maui.Core.Hosting;
```

### Register the Handler

In the `CreateMauiApp()` method, add `.ConfigureSyncfusionCore()` to the builder chain:

```csharp
using Microsoft.Extensions.Logging;
using Syncfusion.Maui.Core.Hosting;

namespace AvatarViewDemo
{
    public static class MauiProgram
    {
        public static MauiApp CreateMauiApp()
        {
            var builder = MauiApp.CreateBuilder();
            builder
                .UseMauiApp<App>()
                .ConfigureSyncfusionCore()  // ← Add this line
                .ConfigureFonts(fonts =>
                {
                    fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                    fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
                });

#if DEBUG
            builder.Logging.AddDebug();
#endif

            return builder.Build();
        }
    }
}
```

**Important:** Place `.ConfigureSyncfusionCore()` after `.UseMauiApp<App>()` and before `.ConfigureFonts()`.

## Step 4: Add Avatar View to Your Page

### Import the Namespace

In your XAML file (e.g., `MainPage.xaml`), add the namespace declaration:

```xaml
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:sfavatar="clr-namespace:Syncfusion.Maui.Core;assembly=Syncfusion.Maui.Core"
             x:Class="AvatarViewDemo.MainPage">
    
    <!-- Your content here -->
    
</ContentPage>
```

### Create a Basic Avatar View

Add the SfAvatarView control in your layout:

```xaml
<ContentPage xmlns:sfavatar="clr-namespace:Syncfusion.Maui.Core;assembly=Syncfusion.Maui.Core">
    <Grid>
        <sfavatar:SfAvatarView 
            HorizontalOptions="Center"
            VerticalOptions="Center" />
    </Grid>
</ContentPage>
```

This creates a default avatar view with the built-in vector image.

## Step 5: Add a Custom Image

To display a custom user image, you need to add an image file to your project and reference it.

### Add Image to Project

1. Add your image file (e.g., `user_profile.png`) to the `Resources/Images` folder
2. Ensure the build action is set to **MauiImage**
3. The image will be automatically processed by MAUI

### Display the Image

**XAML:**
```xaml
<sfavatar:SfAvatarView 
    ContentType="Custom"
    ImageSource="user_profile.png"
    WidthRequest="100"
    HeightRequest="100"
    CornerRadius="50"
    Stroke="Black"
    StrokeThickness="2"
    HorizontalOptions="Center"
    VerticalOptions="Center" />
```

**C#:**
```csharp
using Syncfusion.Maui.Core;

namespace AvatarViewDemo
{
    public partial class MainPage : ContentPage
    {
        public MainPage()
        {
            InitializeComponent();
            
            var avatarView = new SfAvatarView
            {
                ContentType = ContentType.Custom,
                ImageSource = "user_profile.png",
                WidthRequest = 100,
                HeightRequest = 100,
                CornerRadius = 50,
                Stroke = Colors.Black,
                StrokeThickness = 2,
                HorizontalOptions = LayoutOptions.Center,
                VerticalOptions = LayoutOptions.Center
            };
            
            Content = avatarView;
        }
    }
}
```

## Complete Example: MainPage.xaml

```xaml
<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:sfavatar="clr-namespace:Syncfusion.Maui.Core;assembly=Syncfusion.Maui.Core"
             x:Class="AvatarViewDemo.MainPage">

    <ScrollView>
        <VerticalStackLayout Spacing="25" Padding="30">
            
            <!-- Default Avatar -->
            <Label Text="Default Avatar" FontSize="18" FontAttributes="Bold" />
            <sfavatar:SfAvatarView 
                ContentType="Default"
                Background="CornflowerBlue"
                WidthRequest="80"
                HeightRequest="80"
                CornerRadius="40"
                HorizontalOptions="Center" />
            
            <!-- Custom Image Avatar -->
            <Label Text="Custom Image" FontSize="18" FontAttributes="Bold" />
            <sfavatar:SfAvatarView 
                ContentType="Custom"
                ImageSource="user_profile.png"
                WidthRequest="100"
                HeightRequest="100"
                CornerRadius="50"
                Stroke="Gray"
                StrokeThickness="2"
                HorizontalOptions="Center" />
            
            <!-- Initials Avatar -->
            <Label Text="Initials Avatar" FontSize="18" FontAttributes="Bold" />
            <sfavatar:SfAvatarView 
                ContentType="Initials"
                InitialsType="DoubleCharacter"
                AvatarName="John Doe"
                Background="OrangeRed"
                InitialsColor="White"
                WidthRequest="80"
                HeightRequest="80"
                CornerRadius="40"
                HorizontalOptions="Center" />
            
        </VerticalStackLayout>
    </ScrollView>

</ContentPage>
```

## Troubleshooting

### Issue: Handler Not Registered Error

**Error Message:**
```
Handler not registered for type Syncfusion.Maui.Core.SfAvatarView
```

**Solution:**
Ensure `.ConfigureSyncfusionCore()` is called in `MauiProgram.cs`:

```csharp
builder.UseMauiApp<App>()
       .ConfigureSyncfusionCore()  // Must be present
```

### Issue: Image Not Displaying

**Possible Causes:**
1. Image file not in `Resources/Images` folder
2. Build action not set to **MauiImage**
3. Incorrect file name or path

**Solution:**
- Verify the image exists in `Resources/Images/`
- Check the file name matches exactly (case-sensitive on some platforms)
- Rebuild the project

### Issue: NuGet Package Not Found

**Solution:**
- Check your NuGet package source settings
- Ensure you have internet connectivity
- Try clearing NuGet cache: `dotnet nuget locals all --clear`
- Verify package name: **Syncfusion.Maui.Core** (not Syncfusion.MAUI.Core)

### Issue: Namespace Not Found

**Error Message:**
```
The type or namespace name 'Syncfusion' could not be found
```

**Solution:**
- Verify the NuGet package is installed
- Clean and rebuild the solution
- Check the using directive: `using Syncfusion.Maui.Core;`
- Restart Visual Studio if necessary

## Best Practices

1. **Always register the handler** - Don't skip the `.ConfigureSyncfusionCore()` call
2. **Use appropriate image sizes** - Don't use unnecessarily large images for small avatars
3. **Test on multiple platforms** - Avatar rendering may vary slightly between platforms
4. **Consider fallbacks** - Provide initials or default avatars when images fail to load
5. **Optimize image resources** - Use compressed images to reduce app size

# Visual Styles in .NET MAUI Avatar View

The SfAvatarView control supports built-in visual styles that provide consistent sizing and shapes across your application. This guide covers Custom, Circle, and Square visual styles with their size variations.

## Table of Contents

- [Overview](#overview)
- [Visual Style Types](#visual-style-types)
- [Custom Style](#custom-style)
- [Circle Styles](#circle-styles)
  - [Size Variations](#circle-size-variations)
  - [Implementation Examples](#circle-implementation)
- [Square Styles](#square-styles)
  - [Size Variations](#square-size-variations)
  - [Implementation Examples](#square-implementation)
- [Choosing Visual Styles](#choosing-visual-styles)
- [Combining Styles with Other Properties](#combining-styles-with-other-properties)

## Overview

Visual styles in SfAvatarView are controlled by two main properties:

- **AvatarShape** - Determines the shape (`Custom`, `Circle`, `Square`)
- **AvatarSize** - Determines the size preset (`ExtraSmall`, `Small`, `Medium`, `Large`, `ExtraLarge`)

These properties work together to create consistent, predefined avatar appearances without manually setting width, height, and corner radius.

## Visual Style Types

| Style | Description | Best For |
|-------|-------------|----------|
| **Custom** | Manually defined dimensions | Precise control, unique sizes |
| **Circle** | Circular avatars with size presets | Profile pictures, user avatars |
| **Square** | Square avatars with size presets | App icons, badges, groups |

**Default:** `Custom` style with manual dimension control

## Custom Style

The **Custom** style gives you complete control over dimensions and shape by manually setting properties.

### When to Use Custom Style

- Need exact pixel dimensions
- Responsive layouts with dynamic sizing
- Unique shapes beyond circles and squares
- Per-avatar customization required

### Implementation

**XAML:**
```xaml
<sfavatar:SfAvatarView 
    ContentType="Custom"
    ImageSource="user.png"
    WidthRequest="75"
    HeightRequest="75"
    CornerRadius="15"
    Stroke="Gray"
    StrokeThickness="2" />
```

**C#:**
```csharp
var avatarView = new SfAvatarView
{
    ContentType = ContentType.Custom,
    ImageSource = "user.png",
    WidthRequest = 75,
    HeightRequest = 75,
    CornerRadius = 15,
    Stroke = Colors.Gray,
    StrokeThickness = 2
};
```

### Key Points

- Must manually set `WidthRequest`, `HeightRequest`, and `CornerRadius`
- Full flexibility in dimensions
- No preset sizes applied
- Default when `AvatarShape` is not specified

## Circle Styles

Circle styles provide five predefined circular avatar sizes.

### Circle Size Variations

| Size | Typical Dimensions | Use Case |
|------|-------------------|----------|
| **ExtraSmall** | ~32px | Dense lists, tags |
| **Small** | ~48px | Compact lists, comments |
| **Medium** | ~64px | Standard lists, cards |
| **Large** | ~80px | Detail views, headers |
| **ExtraLarge** | ~96px+ | Profile pages, hero sections |

**Note:** Exact dimensions are managed by the control based on platform and theme.

### Circle Implementation

#### Single Circle Avatar

**XAML:**
```xaml
<sfavatar:SfAvatarView 
    ContentType="Custom"
    ImageSource="user.png"
    AvatarShape="Circle"
    AvatarSize="Large"
    Stroke="Black"
    StrokeThickness="1"
    HorizontalOptions="Center"
    VerticalOptions="Center" />
```

**C#:**
```csharp
var avatarView = new SfAvatarView
{
    ContentType = ContentType.Custom,
    ImageSource = "user.png",
    AvatarShape = AvatarShape.Circle,
    AvatarSize = AvatarSize.Large,
    Stroke = Colors.Black,
    StrokeThickness = 1,
    HorizontalOptions = LayoutOptions.Center,
    VerticalOptions = LayoutOptions.Center
};
```

#### All Circle Sizes Example

**XAML:**
```xaml
<ContentPage.Resources>
    <ResourceDictionary>
        <Style x:Key="CircleAvatarStyle" TargetType="sfavatar:SfAvatarView">
            <Setter Property="VerticalOptions" Value="Center"/>
            <Setter Property="HorizontalOptions" Value="Center"/>
            <Setter Property="ContentType" Value="Custom"/>
            <Setter Property="ImageSource" Value="user.png"/>
            <Setter Property="Stroke" Value="Black"/>
            <Setter Property="StrokeThickness" Value="1"/>
            <Setter Property="AvatarShape" Value="Circle"/>
        </Style>
    </ResourceDictionary>
</ContentPage.Resources>

<StackLayout Orientation="Vertical" Spacing="20" Padding="20">
    
    <!-- Extra Large Circle -->
    <StackLayout HorizontalOptions="Center">
        <sfavatar:SfAvatarView 
            AvatarSize="ExtraLarge"
            Style="{StaticResource CircleAvatarStyle}"/>
        <Label Text="ExtraLarge" 
               HorizontalOptions="Center"
               FontAttributes="Bold"
               FontSize="10"/>
    </StackLayout>
    
    <!-- Large Circle -->
    <StackLayout HorizontalOptions="Center">
        <sfavatar:SfAvatarView 
            AvatarSize="Large"
            Style="{StaticResource CircleAvatarStyle}"/>
        <Label Text="Large" 
               HorizontalOptions="Center"
               FontAttributes="Bold"
               FontSize="10"/>
    </StackLayout>
    
    <!-- Medium Circle -->
    <StackLayout HorizontalOptions="Center">
        <sfavatar:SfAvatarView 
            AvatarSize="Medium"
            Style="{StaticResource CircleAvatarStyle}"/>
        <Label Text="Medium" 
               HorizontalOptions="Center"
               FontAttributes="Bold"
               FontSize="10"/>
    </StackLayout>
    
    <!-- Small Circle -->
    <StackLayout HorizontalOptions="Center">
        <sfavatar:SfAvatarView 
            AvatarSize="Small"
            Style="{StaticResource CircleAvatarStyle}"/>
        <Label Text="Small" 
               HorizontalOptions="Center"
               FontAttributes="Bold"
               FontSize="10"/>
    </StackLayout>
    
    <!-- Extra Small Circle -->
    <StackLayout HorizontalOptions="Center">
        <sfavatar:SfAvatarView 
            AvatarSize="ExtraSmall"
            Style="{StaticResource CircleAvatarStyle}"/>
        <Label Text="ExtraSmall" 
               HorizontalOptions="Center"
               FontAttributes="Bold"
               FontSize="10"/>
    </StackLayout>
    
</StackLayout>
```

**C# Implementation:**
```csharp
var mainLayout = new StackLayout
{
    Orientation = StackOrientation.Vertical,
    Spacing = 20,
    Padding = 20,
    HorizontalOptions = LayoutOptions.Center
};

// Helper method to create avatar with label
StackLayout CreateAvatarWithLabel(AvatarSize size, string label)
{
    var avatar = new SfAvatarView
    {
        ContentType = ContentType.Custom,
        ImageSource = "user.png",
        AvatarShape = AvatarShape.Circle,
        AvatarSize = size,
        Stroke = Colors.Black,
        StrokeThickness = 1,
        HorizontalOptions = LayoutOptions.Center,
        VerticalOptions = LayoutOptions.Center
    };
    
    var labelView = new Label
    {
        Text = label,
        HorizontalOptions = LayoutOptions.Center,
        FontAttributes = FontAttributes.Bold,
        FontSize = 10
    };
    
    var container = new StackLayout
    {
        HorizontalOptions = LayoutOptions.Center
    };
    container.Children.Add(avatar);
    container.Children.Add(labelView);
    
    return container;
}

// Add all sizes
mainLayout.Children.Add(CreateAvatarWithLabel(AvatarSize.ExtraLarge, "ExtraLarge"));
mainLayout.Children.Add(CreateAvatarWithLabel(AvatarSize.Large, "Large"));
mainLayout.Children.Add(CreateAvatarWithLabel(AvatarSize.Medium, "Medium"));
mainLayout.Children.Add(CreateAvatarWithLabel(AvatarSize.Small, "Small"));
mainLayout.Children.Add(CreateAvatarWithLabel(AvatarSize.ExtraSmall, "ExtraSmall"));

Content = mainLayout;
```

### Circle Style Use Cases

**ExtraSmall Circles:**
- Comment author avatars
- Mention chips
- Reaction indicators
- Dense activity feeds

**Small Circles:**
- List item avatars (contacts, messages)
- Compact navigation elements
- Secondary user indicators

**Medium Circles:**
- Standard list views
- Card headers
- Search results
- Chat messages

**Large Circles:**
- Detail page headers
- Active conversation indicator
- Feature highlights
- Navigation drawer profile

**ExtraLarge Circles:**
- Profile pages
- User settings
- Account management
- Hero sections

## Square Styles

Square styles provide five predefined square avatar sizes with slightly rounded corners.

### Square Size Variations

| Size | Typical Dimensions | Use Case |
|------|-------------------|----------|
| **ExtraSmall** | ~32px | App icons, badges |
| **Small** | ~48px | Thumbnails, gallery items |
| **Medium** | ~64px | Media items, attachments |
| **Large** | ~80px | Feature images, tiles |
| **ExtraLarge** | ~96px+ | Hero images, covers |

### Square Implementation

#### Single Square Avatar

**XAML:**
```xaml
<sfavatar:SfAvatarView 
    ContentType="Custom"
    ImageSource="app_icon.png"
    AvatarShape="Square"
    AvatarSize="Medium"
    Stroke="Gray"
    StrokeThickness="2"
    HorizontalOptions="Center"
    VerticalOptions="Center" />
```

**C#:**
```csharp
var avatarView = new SfAvatarView
{
    ContentType = ContentType.Custom,
    ImageSource = "app_icon.png",
    AvatarShape = AvatarShape.Square,
    AvatarSize = AvatarSize.Medium,
    Stroke = Colors.Gray,
    StrokeThickness = 2,
    HorizontalOptions = LayoutOptions.Center,
    VerticalOptions = LayoutOptions.Center
};
```

#### All Square Sizes Example

**XAML:**
```xaml
<ContentPage.Resources>
    <ResourceDictionary>
        <Style x:Key="SquareAvatarStyle" TargetType="sfavatar:SfAvatarView">
            <Setter Property="VerticalOptions" Value="Center"/>
            <Setter Property="HorizontalOptions" Value="Center"/>
            <Setter Property="ContentType" Value="Custom"/>
            <Setter Property="ImageSource" Value="app_icon.png"/>
            <Setter Property="Stroke" Value="Black"/>
            <Setter Property="StrokeThickness" Value="2"/>
            <Setter Property="AvatarShape" Value="Square"/>
        </Style>
    </ResourceDictionary>
</ContentPage.Resources>

<Grid RowDefinitions="*,*" 
      ColumnDefinitions="*,*,*,*,*"
      HorizontalOptions="Center"
      VerticalOptions="Center">
    
    <!-- Row 0: Avatars -->
    <sfavatar:SfAvatarView Grid.Row="0" Grid.Column="4"
                           AvatarSize="ExtraLarge"
                           Style="{StaticResource SquareAvatarStyle}"/>
    
    <sfavatar:SfAvatarView Grid.Row="0" Grid.Column="3"
                           AvatarSize="Large"
                           Style="{StaticResource SquareAvatarStyle}"/>
    
    <sfavatar:SfAvatarView Grid.Row="0" Grid.Column="2"
                           AvatarSize="Medium"
                           Style="{StaticResource SquareAvatarStyle}"/>
    
    <sfavatar:SfAvatarView Grid.Row="0" Grid.Column="1"
                           AvatarSize="Small"
                           Style="{StaticResource SquareAvatarStyle}"/>
    
    <sfavatar:SfAvatarView Grid.Row="0" Grid.Column="0"
                           AvatarSize="ExtraSmall"
                           Style="{StaticResource SquareAvatarStyle}"/>
    
    <!-- Row 1: Labels -->
    <Label Grid.Row="1" Grid.Column="4" 
           Text="ExtraLarge"
           FontAttributes="Bold"
           FontSize="10"
           HorizontalOptions="Center"
           VerticalOptions="Center"/>
    
    <Label Grid.Row="1" Grid.Column="3" 
           Text="Large"
           FontAttributes="Bold"
           FontSize="10"
           HorizontalOptions="Center"
           VerticalOptions="Center"/>
    
    <Label Grid.Row="1" Grid.Column="2" 
           Text="Medium"
           FontAttributes="Bold"
           FontSize="10"
           HorizontalOptions="Center"
           VerticalOptions="Center"/>
    
    <Label Grid.Row="1" Grid.Column="1" 
           Text="Small"
           FontAttributes="Bold"
           FontSize="10"
           HorizontalOptions="Center"
           VerticalOptions="Center"/>
    
    <Label Grid.Row="1" Grid.Column="0" 
           Text="ExtraSmall"
           FontAttributes="Bold"
           FontSize="10"
           HorizontalOptions="Center"
           VerticalOptions="Center"/>
</Grid>
```

**C# Implementation:**
```csharp
var grid = new Grid
{
    HorizontalOptions = LayoutOptions.Center,
    VerticalOptions = LayoutOptions.Center
};

grid.RowDefinitions.Add(new RowDefinition { Height = GridLength.Star });
grid.RowDefinitions.Add(new RowDefinition { Height = GridLength.Star });

for (int i = 0; i < 5; i++)
{
    grid.ColumnDefinitions.Add(new ColumnDefinition { Width = GridLength.Star });
}

// Create avatars
var sizes = new[] 
{ 
    (AvatarSize.ExtraSmall, "ExtraSmall", 0),
    (AvatarSize.Small, "Small", 1),
    (AvatarSize.Medium, "Medium", 2),
    (AvatarSize.Large, "Large", 3),
    (AvatarSize.ExtraLarge, "ExtraLarge", 4)
};

foreach (var (size, label, column) in sizes)
{
    var avatar = new SfAvatarView
    {
        ContentType = ContentType.Custom,
        ImageSource = "app_icon.png",
        AvatarShape = AvatarShape.Square,
        AvatarSize = size,
        Stroke = Colors.Black,
        StrokeThickness = 2,
        HorizontalOptions = LayoutOptions.Center,
        VerticalOptions = LayoutOptions.Center
    };
    
    grid.Add(avatar, column, 0);
    
    var labelView = new Label
    {
        Text = label,
        FontAttributes = FontAttributes.Bold,
        FontSize = 10,
        HorizontalOptions = LayoutOptions.Center,
        VerticalOptions = LayoutOptions.Center
    };
    
    grid.Add(labelView, column, 1);
}

Content = grid;
```

### Square Style Use Cases

**ExtraSmall Squares:**
- App badges
- File type indicators
- Category icons
- Status indicators

**Small Squares:**
- Attachment thumbnails
- Gallery previews
- Quick action tiles
- Mini cards

**Medium Squares:**
- Photo galleries
- Document previews
- Media playlists
- Product thumbnails

**Large Squares:**
- Album covers
- Featured images
- Tile navigation
- Dashboard widgets

**ExtraLarge Squares:**
- Hero images
- Cover photos
- Banner images
- Feature showcases

## Choosing Visual Styles

### Circle vs Square Decision Matrix

| Content Type | Recommended Shape | Reason |
|--------------|-------------------|---------|
| Profile photos | Circle | Traditional, friendly |
| Team/group | Circle | Personal connection |
| App icons | Square | Standard convention |
| Media content | Square | Efficient space use |
| Documents | Square | Represents files |
| Contacts | Circle | Personal touch |
| Organizations | Square or Circle | Brand preference |

### When to Use Preset Sizes

**Use AvatarSize presets when:**
- Building consistent UI across features
- Following design system guidelines
- Need responsive scaling
- Want platform-appropriate sizing
- Rapid prototyping

**Use Custom sizing when:**
- Exact pixel dimensions required
- Responsive layouts with calculations
- Unique design requirements
- Animation or transform scenarios
- Per-item size variations

## Combining Styles with Other Properties

### Preset Sizes with Custom Colors

```csharp
var avatar = new SfAvatarView
{
    ContentType = ContentType.Initials,
    AvatarName = "John Doe",
    AvatarShape = AvatarShape.Circle,
    AvatarSize = AvatarSize.Large,
    Background = Colors.Navy,
    InitialsColor = Colors.White,
    Stroke = Colors.Gold,
    StrokeThickness = 3
};
```

### Preset Sizes with Content Types

```csharp
// Image content
var imageAvatar = new SfAvatarView
{
    ContentType = ContentType.Custom,
    ImageSource = "photo.png",
    AvatarShape = AvatarShape.Circle,
    AvatarSize = AvatarSize.Medium
};

// Initials content
var initialsAvatar = new SfAvatarView
{
    ContentType = ContentType.Initials,
    AvatarName = "Sarah",
    AvatarShape = AvatarShape.Circle,
    AvatarSize = AvatarSize.Medium
};

// Avatar character
var characterAvatar = new SfAvatarView
{
    ContentType = ContentType.AvatarCharacter,
    AvatarCharacter = AvatarCharacter.Avatar5,
    AvatarShape = AvatarShape.Square,
    AvatarSize = AvatarSize.Large
};
```

### Mixing Preset and Custom Styles

```csharp
// Use preset for consistent base size
var avatar = new SfAvatarView
{
    AvatarShape = AvatarShape.Circle,
    AvatarSize = AvatarSize.Large
};

// Then customize specific properties
avatar.Stroke = brandColor;
avatar.StrokeThickness = 4;
avatar.ContentPadding = 5;
```

## Style Best Practices

1. **Consistency is key** - Pick a style system and stick to it throughout your app
2. **Use presets for standard cases** - Save custom sizing for special needs
3. **Respect platform conventions** - Circles for people, squares for content
4. **Test on multiple devices** - Preset sizes scale better across screens
5. **Document your choices** - Create a style guide for your team

## Common Patterns

### Adaptive Size by Context

```csharp
public SfAvatarView CreateContextualAvatar(string context, string userName)
{
    AvatarSize size = context switch
    {
        "list" => AvatarSize.Small,
        "detail" => AvatarSize.Large,
        "profile" => AvatarSize.ExtraLarge,
        _ => AvatarSize.Medium
    };
    
    return new SfAvatarView
    {
        ContentType = ContentType.Initials,
        AvatarName = userName,
        AvatarShape = AvatarShape.Circle,
        AvatarSize = size
    };
}
```

### Consistent Avatar Factory

```csharp
public class AvatarFactory
{
    private readonly Color _brandColor;
    
    public AvatarFactory(Color brandColor)
    {
        _brandColor = brandColor;
    }
    
    public SfAvatarView CreateCircleAvatar(AvatarSize size, string name)
    {
        return new SfAvatarView
        {
            ContentType = ContentType.Initials,
            AvatarName = name,
            AvatarShape = AvatarShape.Circle,
            AvatarSize = size,
            Stroke = _brandColor,
            StrokeThickness = 2,
            AvatarColorMode = AvatarColorMode.DarkBackground
        };
    }
    
    public SfAvatarView CreateSquareAvatar(AvatarSize size, string imagePath)
    {
        return new SfAvatarView
        {
            ContentType = ContentType.Custom,
            ImageSource = imagePath,
            AvatarShape = AvatarShape.Square,
            AvatarSize = size,
            Stroke = _brandColor,
            StrokeThickness = 2
        };
    }
}
```

---
name: syncfusion-maui-avatar-view
description: Implements Syncfusion .NET MAUI Avatar View (SfAvatarView) for displaying user profile pictures, initials, or group avatars. Use when working with avatar views, profile pictures, user images, initials display, profile icons, or contact images. Ideal for implementing user profile displays, contact lists, chat interfaces, or social feeds.
metadata:
  author: "Syncfusion Inc"
  version: "34.1.29"
---

# Implementing .NET MAUI Avatar Views

The Syncfusion .NET MAUI Avatar View (SfAvatarView) provides a graphical representation of user images with support for custom images, initials, preset avatars, and group views. It offers extensive customization including shapes, colors, sizes, and badge integration.

## When to Use This Skill

Use this skill when the user needs to:
- **Display user profile pictures** in applications (social apps, contact lists, chat interfaces)
- **Show user initials** when images aren't available (single or double character)
- **Create group avatars** displaying multiple users (up to 3 images/initials)
- **Add badges to avatars** for status indicators or notifications
- **Implement circular or square profile images** with customizable sizes
- **Display preset avatar characters** from built-in vector images
- **Customize avatar appearance** with colors, gradients, strokes, and sizing
- **Build user identification UI** for any MAUI application requiring visual user representation

## Component Overview

**SfAvatarView** is a versatile control for displaying user avatars with five content types:
1. **Default** - Built-in vector image
2. **Initials** - Text-based avatars (single/double character)
3. **Custom** - User-provided images
4. **AvatarCharacter** - Preset vector images
5. **Group** - Multiple users in one view (up to 3)

**Key capabilities:**
- Multiple shapes (Circle, Square, Custom)
- Five size presets (ExtraSmall to ExtraLarge)
- Automatic color generation (Dark/Light backgrounds)
- Badge integration for status/notifications
- Gradient backgrounds and stroke customization
- Font and aspect ratio controls
- MVVM-friendly with data binding support

## Documentation and Navigation Guide

### Getting Started

📄 **Read:** [references/getting-started.md](references/getting-started.md)

When you need to:
- Install and configure the Avatar View component
- Register Syncfusion handlers in MauiProgram.cs
- Create your first basic avatar view
- Add custom images to the avatar
- Set up initial XAML and C# implementation

### Content Types and Display Modes

📄 **Read:** [references/content-types.md](references/content-types.md)

When you need to:
- Choose between Default, Initials, Custom, AvatarCharacter, or Group content types
- Display single or double character initials
- Set up preset avatar characters
- Create group views with multiple images or initials
- Mix images and initials in group views
- Customize initials color or background colors in groups
- Understand when to use each content type

### Customization and Styling

📄 **Read:** [references/customization.md](references/customization.md)

When you need to:
- Control image aspect ratios (AspectFit, AspectFill, Fill, Center)
- Customize colors (stroke, background, automatic dark/light)
- Apply gradient backgrounds
- Set sizing properties (width, height, corner radius)
- Adjust stroke thickness and content padding
- Configure font properties (size, family, attributes, auto-scaling)
- Create custom styled avatars beyond built-in presets

### Visual Styles and Sizes

📄 **Read:** [references/visual-styles.md](references/visual-styles.md)

When you need to:
- Use built-in circle sizes (ExtraSmall to ExtraLarge)
- Use built-in square sizes (ExtraSmall to ExtraLarge)
- Apply consistent visual styles across multiple avatars
- Understand AvatarShape and AvatarSize properties
- Create uniform avatar displays with predefined styles

### BadgeView Integration

📄 **Read:** [references/badgeview-integration.md](references/badgeview-integration.md)

When you need to:
- Add notification badges to avatars
- Display status indicators (online, away, busy)
- Position badges on avatars (corners, custom offsets)
- Animate badge appearances
- Integrate SfBadgeView with SfAvatarView
- Show unread message counts or status icons