Avatar List
A list component that displays multiple avatars in a row or column, with optional overlap and max visibility.
The AvatarList component groups together multiple avatars. You can show them in a row or column, stack them with overlap,
and even limit how many are displayed (e.g., "+3 more").
Each item is powered by the Avatar component, so you can customize it with any of its props.
Usage
javascript
1import AvatarList from '@/components/molecules/AvatarList'; 2 3<AvatarList 4 avatars={[ 5 { src: "/avatar1.png", alt: "User 1" }, 6 { letter: "B" }, 7 { src: "/avatar2.png", alt: "User 2" } 8 ]} 9/>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| avatars | array | [] | Each object can contain src/alt or letter. |
| direction | "horizontal" | "vertical" | "horizontal" | Chooses layout direction. |
| overlap | boolean | true | If true, applies negative margins (like Slack or GitHub) so the avatars stack. |
| maxVisible | number | 5 | Max avatars displayed before the last is replaced with +X more. |
| sharedAvatarProps | object | {} | Common props for every Avatar (e.g. size="sm"). |
| className | string | "" | Additional Tailwind classes (overrides defaults if needed) |
Use sharedAvatarProps to set common props for all avatars.
Examples
Horizontal List with Overflow
Set maxVisible to limit how many avatars are shown. The rest will be replaced with a "+X more" indicator.
Vertical Stacking
Set direction="vertical" to stack avatars in a column. You can also adjust the avatar's size with sharedAvatarProps.
No Overlap & Large Avatars
Combine AvatarList with ringColor or status props if you need
to highlight or indicate user presence for each avatar.