Avatar Group
Stack of avatars with overflow count badge.
<arc-avatar-group>Overview
AvatarGroup arranges a collection of arc-avatar components in a horizontally overlapping stack, with a "+N" overflow counter that appears when the number of avatars exceeds the max threshold. The overlap is controlled by three presets (sm -8px, md -12px, lg -16px) applied as negative margin-left on every child except the first.
When avatars are slotted in, the component listens for slotchange events and manages visibility. Avatars beyond the max count are hidden via display: none, and a circular overflow badge (styled to match the avatar aesthetic) shows the remaining count. Each visible avatar gets a descending z-index so earlier avatars stack on top.
AvatarGroup is marked as a hybrid component: the overlapping layout works in pure CSS, but the overflow counter logic (hiding excess avatars and computing the "+N" label) requires JavaScript. The group wrapper uses role="group" with aria-label="Avatar group" for assistive technology, and the overflow badge uses the same Tomorrow font and elevated background as the avatar initials fallback.
Guidelines
When to use
- Set a reasonable max (3-5) to keep the group compact and scannable
- Use consistent avatar sizes within a group for uniform overlap alignment
- Pair with arc-avatar components exclusively; the overlap styling targets slotted children
- Use the md overlap preset for most contexts; sm for tight spaces, lg for larger avatars
- Place in team member sections, comment threads, or collaboration indicators
When not to use
- Do not mix different avatar sizes in the same group; overlap alignment will be inconsistent
- Do not set max to a very high number and rely solely on the counter; limit visible avatars for clarity
- Do not slot non-avatar elements; the overlap margin and z-index logic assumes arc-avatar children
- Do not remove the overflow badge styling; it provides critical information about hidden members
- Do not use AvatarGroup for a single avatar; it only adds wrapper markup
Features
- Automatic "+N" overflow counter when slotted avatars exceed the max threshold
- Three overlap presets: sm (-8px), md (-12px), lg (-16px)
- Dynamic slot management with slotchange listener for visibility toggling
- Descending z-index assignment for correct visual stacking order
- Overflow badge styled to match avatar aesthetics (Tomorrow font, elevated background, circular shape)
- Accessible `role="group"` with `aria-label` on the container
- Exposed CSS parts: group and overflow for external style customization
Preview
A
B
C
Usage
<arc-avatar-group max="3">
<arc-avatar name="Alice"></arc-avatar>
<arc-avatar name="Bob"></arc-avatar>
<arc-avatar name="Charlie"></arc-avatar>
<arc-avatar name="Diana"></arc-avatar>
</arc-avatar-group>import { Avatar, AvatarGroup } from '@arclux/arc-ui-react';
export default function Example() {
return (
<AvatarGroup max="3">
<Avatar name="Alice" />
<Avatar name="Bob" />
<Avatar name="Charlie" />
<Avatar name="Diana" />
</AvatarGroup>
);
}<script setup>
import { Avatar, AvatarGroup } from '@arclux/arc-ui-vue';
</script>
<template>
<AvatarGroup max="3">
<Avatar name="Alice" />
<Avatar name="Bob" />
<Avatar name="Charlie" />
<Avatar name="Diana" />
</AvatarGroup>
</template><script>
import { Avatar, AvatarGroup } from '@arclux/arc-ui-svelte';
</script>
<AvatarGroup max="3">
<Avatar name="Alice" />
<Avatar name="Bob" />
<Avatar name="Charlie" />
<Avatar name="Diana" />
</AvatarGroup>import { Component } from '@angular/core';
import { Avatar, AvatarGroup } from '@arclux/arc-ui-angular';
@Component({
imports: [Avatar, AvatarGroup],
template: `
<arc-avatar-group max="3">
<arc-avatar name="Alice"></arc-avatar>
<arc-avatar name="Bob"></arc-avatar>
<arc-avatar name="Charlie"></arc-avatar>
<arc-avatar name="Diana"></arc-avatar>
</arc-avatar-group>
`,
})
export class MyComponent {}import { Avatar, AvatarGroup } from '@arclux/arc-ui-solid';
export default function Example() {
return (
<AvatarGroup max="3">
<Avatar name="Alice" />
<Avatar name="Bob" />
<Avatar name="Charlie" />
<Avatar name="Diana" />
</AvatarGroup>
);
}import { Avatar, AvatarGroup } from '@arclux/arc-ui-preact';
export default function Example() {
return (
<AvatarGroup max="3">
<Avatar name="Alice" />
<Avatar name="Bob" />
<Avatar name="Charlie" />
<Avatar name="Diana" />
</AvatarGroup>
);
}<!-- Auto-generated by @arclux/prism — do not edit manually -->
<!-- arc-avatar-group — requires avatar-group.css + base.css (or arc-ui.css) -->
<span class="arc-avatar-group">
<div class="group" role="group" aria-label="Avatar group">
AvatarGroup
<span class="group__overflow" style="display:none"></span>
</div>
</span><!-- Auto-generated by @arclux/prism — do not edit manually -->
<!-- arc-avatar-group — self-contained, no external CSS needed -->
<span class="arc-avatar-group" style="display: inline-flex">
<div style="display: flex; align-items: center" role="group" aria-label="Avatar group">
AvatarGroup
<span style="display: inline-flex; align-items: center; justify-content: center; width: 40px; height: 40px; border-radius: 9999px; background: rgb(17, 17, 22); border: 1px solid rgb(34, 34, 41); font-family: 'Tomorrow', system-ui, sans-serif; font-weight: 600; font-size: 12px; color: rgb(124, 124, 137); user-select: none" style="display:none"></span>
</div>
</span>API
maxnumberInfinity- Maximum number of avatars to display. Excess avatars are hidden and a "+N" overflow badge is shown.
overlap'sm' | 'md' | 'lg''md'- Overlap density preset. sm = -8px, md = -12px, lg = -16px negative margin between avatars.