---
title: 'Avatar'
description: 'User profile images and avatar groups with gradient variants'
---

## Overview

Hux UI provides avatar components for displaying user profile images:

- **HuxAvatar** - Circular user images with initials fallback and built-in caching
- **HuxAvatarGroup** - Display multiple avatars with overlapping layouts

### Features

- **Built-in Image Caching** - Network images use Flutter's built-in caching for better performance
- **Loading States** - Smooth loading indicators while images load
- **Error Handling** - Graceful fallback to initials when images fail to load
- **Offline Support** - Cached images work offline

## Component Variants

### Basic Avatar
Simple avatar with name and initials:

![Avatar with Initials](/images/avatar/avatar-initial.png)

```dart
HuxAvatar(
  name: 'John Doe',
  size: HuxAvatarSize.medium,
)
```

### Avatar with Network Image
Avatar with network profile image (automatically cached):

```dart
HuxAvatar(
  name: 'Jane Smith',
  imageUrl: 'https://example.com/profile.jpg',
  size: HuxAvatarSize.large,
)
```

**Features:**
- Automatic image caching for better performance
- Wireframe loading state while downloading
- Graceful fallback to initials if image fails to load

### Avatar with Local Asset Image
Avatar with local asset image (instant loading):

```dart
HuxAvatar(
  name: 'Local User',
  assetImage: 'assets/avatar.png',
  size: HuxAvatarSize.large,
)
```

**Features:**
- Instant loading (no network required)
- Always available (bundled with app)
- Perfect for default avatars or placeholder images

### Network vs Asset Images

| Feature | Network Image (`imageUrl`) | Asset Image (`assetImage`) |
|---------|---------------------------|---------------------------|
| **Loading** | Shows wireframe placeholder | Instant |
| **Availability** | Requires internet | Always available |
| **Updates** | Can be updated remotely | Requires app update |
| **App Size** | No impact | Increases app size |
| **Use Case** | User profile photos | Default avatars, placeholders |

### Gradient Avatar
Avatar with beautiful gradient background:

![Gradient Avatar](/images/avatar/avatar-gradient.png)

```dart
HuxAvatar(
  useGradient: true,
  gradientVariant: HuxAvatarGradient.bluePurple,
  size: HuxAvatarSize.medium,
)
```

### Small Avatar
Compact avatar for tight spaces:
```dart
HuxAvatar(
  name: 'Bob',
  size: HuxAvatarSize.small,
)
```

### Large Avatar
Prominent avatar for important displays:
```dart
HuxAvatar(
  name: 'Alice',
  size: HuxAvatarSize.large,
)
```

### Extra Large Avatar
Hero avatar for main displays:
```dart
HuxAvatar(
  name: 'CEO',
  size: HuxAvatarSize.extraLarge,
  useGradient: true,
  gradientVariant: HuxAvatarGradient.purplePink,
)
```

### Avatar Group
Multiple avatars with overlapping layout:

![Avatar Group](/images/avatar/avatar-group.png)

```dart
HuxAvatarGroup(
  avatars: [
    HuxAvatar(useGradient: true, gradientVariant: HuxAvatarGradient.bluePurple),
    HuxAvatar(useGradient: true, gradientVariant: HuxAvatarGradient.tealCyan),
    HuxAvatar(useGradient: true, gradientVariant: HuxAvatarGradient.orangeRed),
  ],
  overlap: true,
  maxVisible: 3,
)
```

### Spaced Avatar Group
Multiple avatars with spacing between them:

![Avatar Group](/images/avatar/avatar-group2.png)

```dart
HuxAvatarGroup(
  avatars: [
    HuxAvatar(name: 'Team A'),
    HuxAvatar(name: 'Team B'),
    HuxAvatar(name: 'Team C'),
  ],
  overlap: false,
  spacing: 8.0,
)
```

## HuxAvatar

### With Gradient

```dart
HuxAvatar(
  useGradient: true,
  gradientVariant: HuxAvatarGradient.bluePurple,
  size: HuxAvatarSize.medium,
)
```

### Sizes

- `small` - Compact avatar
- `medium` - Standard avatar (default)
- `large` - Prominent avatar
- `extraLarge` - Hero avatar

### Gradient Variants

- `bluePurple` - Blue to purple gradient
- `greenBlue` - Green to blue gradient
- `orangeRed` - Orange to red gradient
- `purplePink` - Purple to pink gradient
- `tealCyan` - Teal to cyan gradient

## HuxAvatarGroup

Display multiple avatars with overlapping or spaced layouts.

```dart
HuxAvatarGroup(
  avatars: [
    HuxAvatar(name: 'Alice'),
    HuxAvatar(name: 'Bob'),
    HuxAvatar(useGradient: true, gradientVariant: HuxAvatarGradient.greenBlue),
  ],
  overlap: true,
  maxVisible: 3,
)
```

<Note>
  Complete avatar documentation is coming soon. See the [example app](https://github.com/lofidesigner/hux/tree/main/example) for more usage patterns.
</Note>
