EZ Circle Avatar

A defensive, consistent, and customizable Flutter avatar widget designed to simplify user profile displays.

🛑 The Problem

Displaying user avatars often involves repetitive boilerplate:

Inconsistent Colors: Generating a background color from a name usually requires custom logic that might differ between screens, leading to a jarring user experience where "John" is red on one screen and blue on another.
Initials Extraction: extracting "JD" from "John Doe" (or handling single names, empty strings, etc.) is tedious to rewrite.
Contrast Issues: Ensuring text is readable against a generated background color is often overlooked.

✅ The EZ Solution

EzCircleAvatar solves these problems automatically:

Consistent Hashing: Uses a deterministic hash of the name to generate the same background color everywhere in your app. "John" will always be the same shade of teal, ensuring UI consistency.
Smart Initials: Automatically extracts initials (e.g., "John Doe" -> "JD", "Alice" -> "A").
Automatic Contrast: intelligently selects a foreground color (black or white) based on the background luminance for perfect readability.
Defensive Design: Handles empty names, null images, and loading errors gracefully.

✨ Features

Deterministic Color Generation: The same name always produces the same color across your app.
Automatic Initials: Robust initials extraction handling multi-word names, single names, tabs, extra spaces, and Unicode.
Readable Text: Auto-calculates contrast for foreground text with proportional font scaling.
Status Indicators: Display presence dots (statusColor) or custom badges (statusWidget) with flexible alignment.
Borders: Configurable borderColor and borderWidth, properly propagating radius constraints.
Interactions: Built-in onTap and onLongPress callbacks with circular ink ripple.
Accessibility First: Automated screen-reader support via Flutter's Semantics and customizable semanticLabel.
Highly Customizable: Override colors, radius, borders, text styles, images, or child widgets easily.
Fallback Support: Shows a proportionally scaled default icon if no name or image is provided.

📦 Installation

flutter pub add ez_circle_avatar

🚀 Usage

Basic (Consistent Color & Initials)

Result: A circle with "JD" and a consistent background color derived from "Jane Doe".

EzCircleAvatar(name: 'Jane Doe')

With Status Indicator (Online/Offline)

EzCircleAvatar(
  name: 'Jane Doe',
  statusColor: Colors.green,
  statusAlignment: Alignment.bottomRight,
)

With Custom Badge

EzCircleAvatar(
  name: 'Jane Doe',
  statusWidget: Container(
    padding: EdgeInsets.all(2),
    decoration: BoxDecoration(color: Colors.red, shape: BoxShape.circle),
    child: Icon(Icons.star, size: 12, color: Colors.white),
  ),
)

Interactive (Tap & Long Press)

EzCircleAvatar(
  name: 'Jane Doe',
  onTap: () => print('Avatar tapped!'),
  onLongPress: () => print('Avatar long-pressed!'),
)

With Border

EzCircleAvatar(
  name: 'Jane Doe',
  borderColor: Colors.blueAccent,
  borderWidth: 2.0,
)

With Image (Graceful Loading)

Shows the image. If it fails to load, falls back to initials "JS" on a colored background.

EzCircleAvatar(
  name: 'John Smith',
  backgroundImage: NetworkImage('https://example.com/avatar.jpg'),
)

Custom Styling & Typography

Override generated color, size, and text styling.

EzCircleAvatar(
  name: 'Admin User',
  radius: 40,
  backgroundColor: Colors.black,
  foregroundColor: Colors.amber,
  textStyle: TextStyle(fontWeight: FontWeight.bold, letterSpacing: 1.5),
)

🤝 Contributing

Contributions are welcome! Please feel free to open an issue or submit a pull request on GitHub.

📜 License

MIT License - see the LICENSE file for details.