Group Avatar #

A Flutter package for displaying group chat avatars with adaptive overlapping layouts. Perfect for chat applications like KakaoTalk, WhatsApp, and Telegram.

Features #

• 🎨 Adaptive Layout: Automatically adjusts layout based on member count
  • 1 member: Single circle avatar
  • 2 members: Two diagonal overlapped circles (top-right & bottom-left)
  • 3 members: Triangular pattern (top-center, bottom-left, bottom-right)
  • 4+ members: 2x2 grid layout (shows first 4 members)
  • Stack layout: Horizontal overlapping layout (left to right)
• 🖼️ Cached Network Images: Uses cached_network_image for efficient image loading
• 🎯 Customizable: Size, border color, border width, placeholder icon, and avatar shape
• 🎭 Placeholder Support: Shows placeholder icons for missing or failed images
• 📱 Theme Aware: Automatically adapts to your app's theme
• 🔢 Counter Badge: Show remaining member count with "+N" badge
• 👆 Gesture Support: Tap, long press, and individual avatar tap callbacks
• 🔲 Multiple Shapes: Circle, square, rounded square
• 📐 Flexible Layouts: Auto (adaptive) or stack (horizontal/vertical overlapping)
• 🎚️ Customizable Overlap: Adjustable overlap ratio for stack layout (0.0 to 1.0)

Installation #

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

dependencies:
  chat_group_avatar: ^0.1.0

Then run:

flutter pub get

Usage #

Basic Usage #

import 'package:chat_group_avatar/group_avatar.dart';

GroupAvatar(
  imageUrls: [
    'https://example.com/avatar1.jpg',
    'https://example.com/avatar2.jpg',
    'https://example.com/avatar3.jpg',
  ],
  size: 138,
)

With Customization #

GroupAvatar(
  imageUrls: [
    'https://example.com/avatar1.jpg',
    'https://example.com/avatar2.jpg',
  ],
  size: 100,
  borderColor: Colors.blue,
  borderWidth: 3.0,
  backgroundColor: Colors.grey[200],
  placeholderIcon: Icon(Icons.account_circle),
)

Different Member Counts #

// Single member
GroupAvatar(
  imageUrls: ['https://example.com/avatar1.jpg'],
  size: 138,
)

// Two members (diagonal overlap)
GroupAvatar(
  imageUrls: [
    'https://example.com/avatar1.jpg',
    'https://example.com/avatar2.jpg',
  ],
  size: 138,
)

// Three members (triangular)
GroupAvatar(
  imageUrls: [
    'https://example.com/avatar1.jpg',
    'https://example.com/avatar2.jpg',
    'https://example.com/avatar3.jpg',
  ],
  size: 138,
)

// Four or more members (2x2 grid)
GroupAvatar(
  imageUrls: [
    'https://example.com/avatar1.jpg',
    'https://example.com/avatar2.jpg',
    'https://example.com/avatar3.jpg',
    'https://example.com/avatar4.jpg',
    'https://example.com/avatar5.jpg', // Only first 4 are shown
  ],
  size: 138,
)

// With counter badge (show +N for remaining members)
GroupAvatar(
  imageUrls: List.generate(10, (i) => 'https://example.com/avatar$i.jpg'),
  size: 138,
  maxVisible: 3,
  showCounter: true,
)

// Stack layout (horizontal overlapping)
GroupAvatar(
  imageUrls: [
    'https://example.com/avatar1.jpg',
    'https://example.com/avatar2.jpg',
    'https://example.com/avatar3.jpg',
  ],
  size: 138,
  layout: GroupAvatarLayout.stack,
  showCounter: true,
)

// Vertical stack layout
GroupAvatar(
  imageUrls: [
    'https://example.com/avatar1.jpg',
    'https://example.com/avatar2.jpg',
    'https://example.com/avatar3.jpg',
  ],
  size: 138,
  layout: GroupAvatarLayout.stack,
  stackDirection: Axis.vertical,
)

// Custom overlap ratio
GroupAvatar(
  imageUrls: [
    'https://example.com/avatar1.jpg',
    'https://example.com/avatar2.jpg',
    'https://example.com/avatar3.jpg',
  ],
  size: 138,
  layout: GroupAvatarLayout.stack,
  overlapRatio: 0.5, // 50% overlap
)

// Stack with different shapes
GroupAvatar(
  imageUrls: [
    'https://example.com/avatar1.jpg',
    'https://example.com/avatar2.jpg',
  ],
  size: 138,
  layout: GroupAvatarLayout.stack,
  shape: AvatarShape.roundedSquare,
)

// With gesture callbacks
GroupAvatar(
  imageUrls: [
    'https://example.com/avatar1.jpg',
    'https://example.com/avatar2.jpg',
  ],
  size: 138,
  onTap: () => print('Group tapped'),
  onLongPress: () => print('Group long pressed'),
  onAvatarTap: (index, url) => print('Avatar $index tapped: $url'),
)

// Different shapes
GroupAvatar(
  imageUrls: ['https://example.com/avatar1.jpg'],
  size: 138,
  shape: AvatarShape.square, // or roundedSquare
)

Parameters #

Layout Details #

Single Avatar (1 member) #

• Displays a single circular avatar at full size

Two Avatars (2 members) #

• Two avatars arranged diagonally
• Bottom-left avatar appears on top
• Top-right avatar appears underneath
• Each avatar is 90/138 of the total size

Three Avatars (3 members) #

• Triangular arrangement
• Top-center, bottom-left, bottom-right positions
• Each avatar is 90/138 of the total size

Four or More Avatars (4+ members) #

• 2x2 grid layout
• No overlap between avatars
• Only the first 4 avatars are displayed (or maxVisible if specified)
• Each cell is 66/138 of the total size

Stack Layout #

• Horizontal overlapping layout (left to right)
• Avatars overlap by 30% of their size
• Useful for member lists or horizontal displays
• Can show counter badge for remaining members

Counter Badge #

• Shows "+N" badge when showCounter is true and there are more members than maxVisible
• Positioned at bottom-right (or right for stack layout)
• Customizable style and background color

Example #

See the example/ directory for a complete example app.

Screenshots #

Basic Layouts (1, 2, 3, 4 members) #

Custom Border & Custom Counter & Custom Placeholder #

Stack Counter & Square (2, 3, 4 members) #

Rounded Square (2, 3 members) #

Gesture Events (Long Press & Tap) #

Rounded Square 4, Custom Counter, Stack #

Vertical Stack & Custom Overlap & Different Shapes #

Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

License #

This project is licensed under the MIT License - see the LICENSE file for details.

Related Packages #

• avatar_stack - Horizontal overlapping avatars
• cached_network_image - Image caching (used internally)

Support #

If you encounter any issues or have feature requests, please file an issue on the GitHub repository.