My Profile Avatar

A customizable Flutter package for displaying profile avatars with support for multiple image sources including network images, local files, name initials, and placeholder icons.

✨ Features

🌐 Network Images: Display avatars from URLs with built-in caching support
📁 Local Files: Load avatar images from device storage
🔤 Name Initials: Generate text-based avatars from user names
🎭 Placeholder Icons: Show default avatar icons when no image is available
🎨 Customizable Styling: Control size, colors, and border radius
⏳ Loading States: Built-in loading indicators for network images
🛡️ Error Handling: Graceful fallbacks when images fail to load
📱 Platform Support: Works on iOS, Android, Web, and Desktop

📱 Screenshots

Demo App Overview	Interactive Controls

🚀 Getting Started

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  my_profile_avatar: ^1.0.0

Then run:

flutter pub get

Import

import 'package:my_profile_avatar/my_profile_avatar.dart';

📖 Usage

Basic Usage

MyProfileAvatar(
  style: MyProfileAvatarStyle(
    size: 60,
    color: Colors.blue,
    radius: 30,
  ),
  urlImage: 'https://example.com/avatar.jpg',
)

Different Avatar Types

Network Image Avatar

MyProfileAvatar(
  style: MyProfileAvatarStyle(
    size: 80,
    color: Colors.blue,
    radius: 40,
  ),
  urlImage: 'https://images.pexels.com/photos/220453/pexels-photo-220453.jpeg',
)

Name Initials Avatar

MyProfileAvatar(
  style: MyProfileAvatarStyle(
    size: 60,
    color: Colors.green,
    radius: 30,
  ),
  name: 'John Doe',
)

Local File Avatar

MyProfileAvatar(
  style: MyProfileAvatarStyle(
    size: 100,
    color: Colors.purple,
    radius: 50,
  ),
  pathImage: '/path/to/local/image.jpg',
)

Placeholder Avatar

MyProfileAvatar(
  style: MyProfileAvatarStyle(
    size: 50,
    color: Colors.grey,
    radius: 25,
  ),
  // No image sources provided - shows placeholder
)

Using the Type Factory Constructor

For more explicit control over avatar types:

// Network image avatar
MyProfileAvatar.type(
  type: MyProfileAvatarType.network,
  value: 'https://example.com/avatar.jpg',
  style: MyProfileAvatarStyle(
    size: 60,
    color: Colors.blue,
  ),
)

// Name initials avatar
MyProfileAvatar.type(
  type: MyProfileAvatarType.name,
  value: 'Alice Johnson',
  style: MyProfileAvatarStyle(
    size: 80,
    color: Colors.green,
  ),
)

Styling Options

The MyProfileAvatarStyle class provides extensive customization options:

MyProfileAvatarStyle(
  size: 100,        // Width and height in logical pixels
  color: Colors.blue, // Primary color for text, icons, and loading indicators
  radius: 50,       // Border radius (50 = perfect circle for size 100)
)

Common Styling Patterns

// Perfect circle
MyProfileAvatarStyle(
  size: 80,
  color: Colors.blue,
  radius: 40, // Half of size
)

// Rounded square
MyProfileAvatarStyle(
  size: 60,
  color: Colors.green,
  radius: 12,
)

// Sharp square
MyProfileAvatarStyle(
  size: 50,
  color: Colors.red,
  radius: 0,
)

🔄 Priority System

The widget automatically determines which content to display based on this priority order:

Local File (pathImage) - Highest priority
Network Image (urlImage)
Name Initials (name)
Placeholder Icon - Lowest priority (fallback)

MyProfileAvatar(
  style: MyProfileAvatarStyle(color: Colors.blue),
  pathImage: '/local/image.jpg',    // This will be shown
  urlImage: 'https://example.com/avatar.jpg', // Ignored
  name: 'John Doe',                 // Ignored
)

🛠️ Advanced Usage

Custom Error Handling

The widget includes built-in error handling, but you can also check the avatar type programmatically:

final avatar = MyProfileAvatar(
  style: MyProfileAvatarStyle(color: Colors.blue),
  urlImage: 'https://example.com/avatar.jpg',
);

// Check what type will be displayed
final avatarType = avatar.getType(); // MyProfileAvatarType.network
final avatarValue = avatar.getValue(); // 'https://example.com/avatar.jpg'

Integration with User Profiles

class UserProfile extends StatelessWidget {
  final User user;

  const UserProfile({required this.user, super.key});

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        MyProfileAvatar(
          style: MyProfileAvatarStyle(
            size: 120,
            color: Theme.of(context).primaryColor,
            radius: 60,
          ),
          urlImage: user.profileImageUrl,
          name: user.fullName,
        ),
        const SizedBox(height: 16),
        Text(user.fullName, style: Theme.of(context).textTheme.headlineSmall),
      ],
    );
  }
}

📋 API Reference