MultipleAvatars Component

The MultipleAvatars component displays a compact grid of 1-4 user avatars within a single avatar-sized container. It's ideal for representing group conversations, collaborative items, or any context where multiple users are associated with a single entity.

Usage

Single User

With a single user, the avatar displays at full size (same as a regular Avatar).

<MultipleAvatars
  users={[{ avatarId: "1", displayName: "Alice Chen" }]}
/>

Two Users

Two users are displayed diagonally: one in the top-left, one in the bottom-right.

<MultipleAvatars
  users={[
    { avatarId: "1", displayName: "Alice Chen" },
    { avatarId: "2", displayName: "Bob Smith" },
  ]}
/>

Three Users

Three users are arranged with one centered on top and two on the bottom row.

<MultipleAvatars
  users={[
    { avatarId: "1", displayName: "Alice Chen" },
    { avatarId: "2", displayName: "Bob Smith" },
    { avatarId: "3", displayName: "Carol Davis" },
  ]}
/>

Four Users

Four users fill a 2x2 grid.

<MultipleAvatars
  users={[
    { avatarId: "1", displayName: "Alice Chen" },
    { avatarId: "2", displayName: "Bob Smith" },
    { avatarId: "3", displayName: "Carol Davis" },
    { avatarId: "4", displayName: "Dan Wilson" },
  ]}
/>

With Profile Pictures

When users have profile pictures, they are displayed instead of the initial-based fallback.

<MultipleAvatars
  users={[
    { avatarId: "1", displayName: "Alice", profilePicture: "https://..." },
    { avatarId: "2", displayName: "Bob", profilePicture: "https://..." },
    { avatarId: "3", displayName: "Carol", profilePicture: "https://..." },
    { avatarId: "4", displayName: "Dan", profilePicture: "https://..." },
  ]}
/>

All Layouts

Here's a comparison of all four layout variations side by side:

1 user

2 users

3 users

4 users

Props

Name	Type	Default	Description
`users`	`[UserDetails] \| [UserDetails, UserDetails] \| [UserDetails, UserDetails, UserDetails] \| [UserDetails, UserDetails, UserDetails, UserDetails]`	-	A tuple of 1-4 UserDetails objects. The component automatically arranges avatars based on the count.

UserDetails Type

Each user in the array must conform to the UserDetails type:

Property	Type	Description
`avatarId`	`string`	Unique identifier for the avatar.
`displayName`	`string`	Display name for the user. Used for aria-label and fallback initial.
`profilePicture`	`string \| undefined`	Optional URL to the user's profile picture.
`presence`	`boolean \| undefined`	Optional presence status. Not displayed in MultipleAvatars (presence badges are disabled).

type UserDetails = {
  avatarId: string;
  displayName: string;
  profilePicture?: string | undefined;
  presence?: boolean | undefined;
};

Behavior

Layout Algorithm

The component uses a 2x2 CSS grid with intelligent cell positioning based on user count:

1 user - Renders a standard full-size Avatar

2 users - Diagonal layout: top-left and bottom-right cells

3 users - Pyramid layout: one spanning top row, two on bottom

4 users - Full 2x2 grid with all cells occupied

Accessibility

The component automatically generates an aria-label listing all user display names (e.g., "group: Alice Chen, Bob Smith, Carol Davis"). For single users, the standard Avatar accessibility attributes apply.

Internal Avatar Settings

Each avatar within the grid is rendered with specific internal settings:

showBorder: false - Borders are hidden to avoid visual clutter

disablePopover: true - Individual avatar popovers are disabled

showPresence: false - Presence badges are hidden to maintain compact layout

Theming

MultipleAvatars inherits its sizing from the theme's avatar variables:

themeDetails.avatarSize - Controls the overall container size

Individual mini-avatars are scaled to 50% of the container size.

Related Components

Avatar - Single user avatar display

AvatarList - Horizontal list of overlapping avatars