Avatar Group

A component to display a group of user avatars representing members of a team, project, or community.

+10K members

1. Copy the component file

Create a new file called avatar-group.jsx in your reusable components folder (for example /src/components/) and paste the following code into it.

import { memo } from "react";
import styles from "./avatar-group.module.css";

const AvatarGroup = (props) => {
  const {
    label,
    avatars,
    additionalText,
    size = 48,
    className,
    ...restProps
  } = props;

  return (
    <div
      {...restProps}
      role="group"
      aria-label={label}
      className={[
        className,
        styles["avatar-group"],
      ].join(" ")}
    >
      {avatars.map((avatarEntry, index) => (
        <a
          key={`avatar-${index}-${avatarEntry.name}`}
          href={avatarEntry.url}
          target="_blank"
          rel="noreferrer noopener"
          style={{
            "--avatar-size": `${size}px`,
          }}
        >
          <img
            src={avatarEntry.image}
            alt={avatarEntry.name || `Avatar ${index + 1}`}
          />
        </a>
      ))}
      {additionalText && (
        <span>
          {additionalText}
        </span>
      )}
    </div>
  );
};

export default memo(AvatarGroup);

2. Copy the CSS module file

In the same folder, create a file called avatar-group.module.css and paste the following CSS.

.avatar-group {
  --avatar-size: 48px;
  --border-color: #ffffff; /* set as per background color of the container */

  @media (prefers-color-scheme: dark) {
    --border-color: #0b0b0c; /* set as per background color of the container in dark mode */
  }

  display:flex;
  align-items: center;

  > a {
    --overlap: calc(6px + calc(var(--avatar-size) / 8));
    box-sizing: border-box;
    margin-left: calc(var(--overlap) * -1);
    width: var(--avatar-size);
    height:var(--avatar-size);
    border:4px solid var(--border-color);
    border-radius:50%;
    flex-shrink: 0;

    &:first-child {
      margin-left: 0;
    }

    > img {
      width: 100%;
      height: 100%;
      object-fit: cover;
    }
  }

  > span {
    text-indent: 2px;
    white-space: nowrap;
    text-overflow: ellipsis;
  }

  > a, span {		
    overflow: hidden;
  }
}

3. Use the component

Now you can import and use the component anywhere in your project.

import AvatarGroup from "@/components/essentials/avatar-group/avatar-group";

const AvatarGroupPreview = () => {
  return (
    <AvatarGroup 
      label="Project members"
      avatars={avatars}
      additionalText="+10K members"
    />
  );
};

const avatars = [
  {
    name: "Darshan Sunil Rajadhyaksha",
    url: "https://github.com/darshan-rajadhyaksha",
    image: "https://avatars.githubusercontent.com/u/70127031?v=4",
  },
  {
    name: "Another Member",
    url: "https://github.com/darshan-rajadhyaksha",
    image: "https://picsum.photos/id/399/256/256",
  },
  {
    name: "Darshan Sunil Rajadhyaksha",
    url: "https://codepen.io/dsr",
    image: "https://assets.codepen.io/1168397/internal/avatars/users/default.png",
  },
  {
    name: "One more another member",
    url: "https://github.com/darshan-rajadhyaksha",
    image: "https://picsum.photos/id/177/256/256",
  }
]

export default AvatarGroupPreview;

Props

Configure the component with the following props:

Prop	Type	Required	Default	Description
label	`string`	Yes	—	Descriptive name for the avatar group. This helps assistive technologies understand what the group of avatars represents (for example, “Project members” or “Community members”).
avatars	`{ name: string; url?: string; image: string }[]`	Yes	`[]`	Array of avatar objects. Each avatar requires a `name` for accessibility and an `image` source. `url` is optional and makes the avatar clickable.
additionalText	`string`	No	—	Additional text displayed alongside the avatars, for example `"+99k members"` or `"+3 more"`.
size	`number`	No	`48`	Size of each avatar in pixels.
className	`string`	No	—	Optional class name for custom styling of the avatar group container.