Developer Docs
Quick reference guides with props tables, usage examples, and best practices for rapid development
AvatarGroup
AvatarGroup
Display multiple avatars with overlapping layout. Automatically shows "+N" overflow indicator when more avatars are provided than the maximum display count. Perfect for showing team members, collaborators, or participants.
Live Example
🔧 Props
| Prop | Type | Default | Description |
|---|---|---|---|
| max | number | 5 | Maximum number of avatars to display before showing "+N" overflow |
| class | string | '' | CSS classes applied to each avatar (e.g., ring-2 ring-white for separation, vwfsize-* for sizing) |
| containerClass | string | '' | CSS classes for the container div |
💻 Basic Usage
Simple avatar group with default settings. Shows first 5 avatars, remaining count in "+N" badge.
// Basic avatar group
AvatarGroup(
Avatar({ name: 'Alice' }),
Avatar({ name: 'Bob' }),
Avatar({ name: 'Charlie' }),
Avatar({ name: 'Diana' }),
Avatar({ name: 'Eve' }),
Avatar({ name: 'Frank' })
) // Shows 5 avatars + "+1"#️⃣ Custom Maximum Count
Control how many avatars are displayed before overflow with the max prop.
Max: 3
Max: 7
// Show only 3 avatars
AvatarGroup(
{ max: 3 },
Avatar({ name: 'Member 1' }),
Avatar({ name: 'Member 2' }),
Avatar({ name: 'Member 3' }),
Avatar({ name: 'Member 4' }),
Avatar({ name: 'Member 5' })
) // Shows 3 avatars + "+2"
// Show 7 avatars
AvatarGroup(
{ max: 7 },
...manyAvatars
)〇 With Ring Borders
Add ring borders to create visual separation between overlapping avatars.
ring-2 ring-white
ring-4 ring-mist
// Thin white ring
AvatarGroup(
{ max: 4, class: 'ring-2 ring-white vwfsize-lg' },
Avatar({ name: 'Alice' }),
Avatar({ name: 'Bob' }),
Avatar({ name: 'Charlie' }),
Avatar({ name: 'Diana' })
)
// Thick colored ring
AvatarGroup(
{ max: 4, class: 'ring-4 ring-mist vwfsize-lg' },
...avatars
)📐 Size Variants
Control avatar size using vwfsize-* utilities in the class prop.
Small (vwfsize-sm)
Medium (vwfsize-md)
Large (vwfsize-lg)
Extra Large (vwfsize-xl)
// Small avatars
AvatarGroup({ max: 5, class: 'vwfsize-sm ring-2 ring-white' }, ...avatars)
// Large avatars
AvatarGroup({ max: 5, class: 'vwfsize-lg ring-2 ring-white' }, ...avatars)
// Extra large
AvatarGroup({ max: 5, class: 'vwfsize-xl ring-3 ring-white' }, ...avatars)🟢 With Status Indicators
Avatars in groups can have status indicators to show presence.
AvatarGroup(
{ max: 4, class: 'vwfsize-lg ring-2 ring-white' },
Avatar({ name: 'Alice', status: 'online' }),
Avatar({ name: 'Bob', status: 'away' }),
Avatar({ name: 'Charlie', status: 'busy' }),
Avatar({ name: 'Diana', status: 'offline' }),
Avatar({ name: 'Eve', status: 'online' })
)⌱ Z-Index Stacking
Avatars are stacked with decreasing z-index from first to last. The first avatar appears on top, the last appears at the bottom.
// Z-index stacking order:
// First avatar = highest z-index (on top)
// Last avatar = lowest z-index (at bottom)
AvatarGroup(
Avatar({ name: 'A' }), // z-index: 5 (on top)
Avatar({ name: 'B' }), // z-index: 4
Avatar({ name: 'C' }), // z-index: 3
Avatar({ name: 'D' }), // z-index: 2
Avatar({ name: 'E' }) // z-index: 1 (at bottom)
)
// Overlap calculation:
// ml-[calc(var(--vwf-size)*-1+var(--spacing))]⚡️ Best Practices
✓ Do This
✓Add ring borders for visual separation
- Use ring-2 ring-white to create clear separation between overlapping avatars.
✓Keep max between 3-7 for readability
- Higher values make individual avatars too small to distinguish.
✓Use consistent avatar sizes
- All avatars in a group should use the same size for visual harmony.
✓Provide meaningful names for accessibility
- Even without images, names generate initials and improve screen reader support.
✓Show "+N" overflow for large groups
- Use max prop to limit display and show "+N" indicator for remaining avatars.
✗ Avoid This
✗Don't set max too high
- Values above 7 make overlapping avatars hard to distinguish.
✗Don't forget ring borders
- Without rings, avatars blend together and lose definition.
✗Don't mix different sizes in one group
- Inconsistent sizing disrupts visual rhythm and alignment.
✗Don't make avatars too small
- Minimum vwfsize-sm recommended for touch targets and visibility.
✨ Key Features
⭑Automatic "+N" Overflow Indicator
- Shows "+N" badge when avatar count exceeds max prop value.
⭑Negative Margin Overlap
- Space-efficient overlapping layout using negative margins.
⭑Z-Index Stacking
- First avatar appears on top, creating natural left-to-right layering.
⭑Full Avatar Props Support
- All Avatar component props work: status indicators, images, icons, etc.
⭑Configurable Max Display
- Control how many avatars display before showing "+N" overflow.
⭑Ring Border Support
- Ring utilities create visual separation between overlapping avatars.
⭑Size Utilities
- All vwfsize-* utilities supported for consistent sizing.
⭑Responsive and Touch-Friendly
- Works across devices with proper touch target sizing.
⭑Accessibility
- Proper ARIA attributes for screen reader support.
Common Use Cases
👥 Team Members
Display project team, collaborators, or organization members.
AvatarGroup(
{ max: 5, class: 'vwfsize-md ring-2 ring-white' },
...teamMembers.map(member =>
Avatar({ name: member.name, status: member.status })
)
)💬 Chat Participants
Show who is in a group chat or conversation.
AvatarGroup(
{ max: 4, class: 'vwfsize-sm ring-2 ring-white' },
...participants.map(p => Avatar({ name: p.name, status: 'online' }))
)🎫 Event Attendees
Display RSVPs or confirmed attendees for events.
AvatarGroup(
{ max: 6, class: 'vwfsize-lg ring-2 ring-white' },
...attendees.map(a => Avatar({ name: a.name }))
)📝 Document Collaborators
Show who has access to or is editing a document.
AvatarGroup(
{ max: 3, class: 'vwfsize-sm ring-1 ring-mist' },
...collaborators.map(c =>
Avatar({ name: c.name, status: c.isEditing ? 'online' : 'away' })
)
)Explore More Components
Browse other component categories