> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thehuxdesign.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Avatar

> 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:

<img src="https://mintcdn.com/thehuxdesign/81AtyNkpXR7HVLTv/images/avatar/avatar-initial.png?fit=max&auto=format&n=81AtyNkpXR7HVLTv&q=85&s=b6b6e698ff4a887f05a09fad4d1af92e" alt="Avatar with Initials" width="800" height="200" data-path="images/avatar/avatar-initial.png" />

```dart theme={null}
HuxAvatar(
  name: 'John Doe',
  size: HuxAvatarSize.medium,
)
```

### Avatar with Network Image

Avatar with network profile image (automatically cached):

```dart theme={null}
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 theme={null}
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:

<img src="https://mintcdn.com/thehuxdesign/81AtyNkpXR7HVLTv/images/avatar/avatar-gradient.png?fit=max&auto=format&n=81AtyNkpXR7HVLTv&q=85&s=54448726a7a494f962245e01fd4520c5" alt="Gradient Avatar" width="800" height="200" data-path="images/avatar/avatar-gradient.png" />

```dart theme={null}
HuxAvatar(
  useGradient: true,
  gradientVariant: HuxAvatarGradient.bluePurple,
  size: HuxAvatarSize.medium,
)
```

### Small Avatar

Compact avatar for tight spaces:

```dart theme={null}
HuxAvatar(
  name: 'Bob',
  size: HuxAvatarSize.small,
)
```

### Large Avatar

Prominent avatar for important displays:

```dart theme={null}
HuxAvatar(
  name: 'Alice',
  size: HuxAvatarSize.large,
)
```

### Extra Large Avatar

Hero avatar for main displays:

```dart theme={null}
HuxAvatar(
  name: 'CEO',
  size: HuxAvatarSize.extraLarge,
  useGradient: true,
  gradientVariant: HuxAvatarGradient.purplePink,
)
```

### Avatar Group

Multiple avatars with overlapping layout:

<img src="https://mintcdn.com/thehuxdesign/81AtyNkpXR7HVLTv/images/avatar/avatar-group.png?fit=max&auto=format&n=81AtyNkpXR7HVLTv&q=85&s=051ec04095b299f5e5d43b453222cf46" alt="Avatar Group" width="800" height="200" data-path="images/avatar/avatar-group.png" />

```dart theme={null}
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:

<img src="https://mintcdn.com/thehuxdesign/81AtyNkpXR7HVLTv/images/avatar/avatar-group2.png?fit=max&auto=format&n=81AtyNkpXR7HVLTv&q=85&s=d6ac09a87dea7597f8a9d5d229735708" alt="Avatar Group" width="800" height="200" data-path="images/avatar/avatar-group2.png" />

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

## HuxAvatar

### With Gradient

```dart theme={null}
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 theme={null}
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>