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:

  1. 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.
  2. Initials Extraction: extracting "JD" from "John Doe" (or handling single names, empty strings, etc.) is tedious to rewrite.
  3. 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.
  • Automatic Initials: Handles first/last names, single names, and edge cases.
  • Readable Text: Auto-calculates contrast for foreground text.
  • Highly Customizable: Override colors, radius, images, or child widgets easily.
  • Fallback Support: Shows a 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 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

Override generated color or contrast.

EzCircleAvatar(
  name: 'Admin User',
  radius: 40,
  backgroundColor: Colors.black,
  foregroundColor: Colors.amber,
)

🀝 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.

Libraries

ez_circle_avatar