Light Dark System

Avatar Group

<cw-avatar-group> | CwAvatarGroup
Since 1.5 experimental

Avatar groups display a stack of overlapping avatars, collapsing anything past a configurable count into a ”+N” indicator.

Avatar groups stack avatars together to represent a set of people or objects — a list of meeting attendees, project collaborators, or assignees on a task. Slot in one or more <cw-avatar> elements and the group handles overlapping them for you. 

<cw-avatar-group>
  <cw-avatar label="Alice" initials="A"></cw-avatar>
  <cw-avatar label="Bob" initials="B"></cw-avatar>
  <cw-avatar label="Carol" initials="C"></cw-avatar>
</cw-avatar-group>

import CwAvatar from '@cordwainer/cw-elements/dist/react/avatar';
import CwAvatarGroup from '@cordwainer/cw-elements/dist/react/avatar-group';

const App = () => (
  <CwAvatarGroup>
    <CwAvatar label="Alice" initials="A" />
    <CwAvatar label="Bob" initials="B" />
    <CwAvatar label="Carol" initials="C" />
  </CwAvatarGroup>
);

Examples

Limiting the Count

Set the max attribute to cap how many avatars are shown. Avatars past that count collapse into a ”+N” indicator. Hover or focus the indicator to see who’s hidden. 

<cw-avatar-group max="3">
  <cw-avatar label="Alice" initials="A"></cw-avatar>
  <cw-avatar label="Bob" initials="B"></cw-avatar>
  <cw-avatar label="Carol" initials="C"></cw-avatar>
  <cw-avatar label="Dave" initials="D"></cw-avatar>
  <cw-avatar label="Erin" initials="E"></cw-avatar>
</cw-avatar-group>

import CwAvatar from '@cordwainer/cw-elements/dist/react/avatar';
import CwAvatarGroup from '@cordwainer/cw-elements/dist/react/avatar-group';

const App = () => (
  <CwAvatarGroup max={3}>
    <CwAvatar label="Alice" initials="A" />
    <CwAvatar label="Bob" initials="B" />
    <CwAvatar label="Carol" initials="C" />
    <CwAvatar label="Dave" initials="D" />
    <CwAvatar label="Erin" initials="E" />
  </CwAvatarGroup>
);

Adjusting the Overlap

Set the overlap attribute to control how many pixels each avatar overlaps the one before it. It defaults to 16. Set it to 0 to lay the avatars out edge-to-edge instead of stacking them. 


<cw-avatar-group overlap="4" style="margin-bottom: 1rem;">
  <cw-avatar label="Alice" initials="A"></cw-avatar>
  <cw-avatar label="Bob" initials="B"></cw-avatar>
  <cw-avatar label="Carol" initials="C"></cw-avatar>
</cw-avatar-group>
<br />
<cw-avatar-group overlap="24">
  <cw-avatar label="Alice" initials="A"></cw-avatar>
  <cw-avatar label="Bob" initials="B"></cw-avatar>
  <cw-avatar label="Carol" initials="C"></cw-avatar>
</cw-avatar-group>

import CwAvatar from '@cordwainer/cw-elements/dist/react/avatar';
import CwAvatarGroup from '@cordwainer/cw-elements/dist/react/avatar-group';

const App = () => (
  <>
    <CwAvatarGroup overlap={4}>
      <CwAvatar label="Alice" initials="A" />
      <CwAvatar label="Bob" initials="B" />
      <CwAvatar label="Carol" initials="C" />
    </CwAvatarGroup>
    <br />
    <CwAvatarGroup overlap={24}>
      <CwAvatar label="Alice" initials="A" />
      <CwAvatar label="Bob" initials="B" />
      <CwAvatar label="Carol" initials="C" />
    </CwAvatarGroup>
  </>
);

Using Images

Avatar groups work the same way with image avatars as they do with initials. As with a standalone avatar, always provide a label for assistive devices. 

<cw-avatar-group>
  <cw-avatar
    image="https://images.unsplash.com/photo-1490150028299-bf57d78394e0?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&q=80&crop=right"
    label="Alice"
  ></cw-avatar>
  <cw-avatar
    image="https://images.unsplash.com/photo-1503454537195-1dcabb73ffb9?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&crop=left&q=80"
    label="Bob"
  ></cw-avatar>
  <cw-avatar
    image="https://images.unsplash.com/photo-1456439663599-95b042d50252?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&crop=left&q=80"
    label="Carol"
  ></cw-avatar>
</cw-avatar-group>

import CwAvatar from '@cordwainer/cw-elements/dist/react/avatar';
import CwAvatarGroup from '@cordwainer/cw-elements/dist/react/avatar-group';

const App = () => (
  <CwAvatarGroup>
    <CwAvatar
      image="https://images.unsplash.com/photo-1490150028299-bf57d78394e0?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&q=80&crop=right"
      label="Alice"
    />
    <CwAvatar
      image="https://images.unsplash.com/photo-1503454537195-1dcabb73ffb9?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&crop=left&q=80"
      label="Bob"
    />
    <CwAvatar
      image="https://images.unsplash.com/photo-1456439663599-95b042d50252?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&crop=left&q=80"
      label="Carol"
    />
  </CwAvatarGroup>
);

Linkable Avatars

Since <cw-avatar> supports href, each avatar in a group can link out on its own — e.g. to that person’s profile page. 

<cw-avatar-group>
  <cw-avatar label="View Alice's profile" initials="A" href="https://example.com/people/alice"></cw-avatar>
  <cw-avatar label="View Bob's profile" initials="B" href="https://example.com/people/bob"></cw-avatar>
  <cw-avatar label="View Carol's profile" initials="C" href="https://example.com/people/carol"></cw-avatar>
</cw-avatar-group>

import CwAvatar from '@cordwainer/cw-elements/dist/react/avatar';
import CwAvatarGroup from '@cordwainer/cw-elements/dist/react/avatar-group';

const App = () => (
  <CwAvatarGroup>
    <CwAvatar label="View Alice's profile" initials="A" href="https://example.com/people/alice" />
    <CwAvatar label="View Bob's profile" initials="B" href="https://example.com/people/bob" />
    <CwAvatar label="View Carol's profile" initials="C" href="https://example.com/people/carol" />
  </CwAvatarGroup>
);

Customizing the Ring Color

Each avatar gets a ring so overlapping ones stay visually distinct — it defaults to matching the page/panel background. When a group sits on a differently-colored surface, override --cw-avatar-group-ring-color to match. 

<div style="background: var(--cw-color-primary-600); padding: 1rem; border-radius: var(--cw-border-radius-medium);">
  <cw-avatar-group style="--cw-avatar-group-ring-color: var(--cw-color-primary-600);">
    <cw-avatar label="Alice" initials="A"></cw-avatar>
    <cw-avatar label="Bob" initials="B"></cw-avatar>
    <cw-avatar label="Carol" initials="C"></cw-avatar>
  </cw-avatar-group>
</div>

import CwAvatar from '@cordwainer/cw-elements/dist/react/avatar';
import CwAvatarGroup from '@cordwainer/cw-elements/dist/react/avatar-group';

const css = `
  .ring-color-demo {
    background: var(--cw-color-primary-600);
    padding: 1rem;
    border-radius: var(--cw-border-radius-medium);
  }

  .ring-color-demo cw-avatar-group {
    --cw-avatar-group-ring-color: var(--cw-color-primary-600);
  }
`;

const App = () => (
  <>
    <div className="ring-color-demo">
      <CwAvatarGroup>
        <CwAvatar label="Alice" initials="A" />
        <CwAvatar label="Bob" initials="B" />
        <CwAvatar label="Carol" initials="C" />
      </CwAvatarGroup>
    </div>

    <style>{css}</style>
  </>
);

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

Script Import Bundler React

To import this component from the CDN using a script tag: 

<script type="module" src="https://cdn.jsdelivr.net/npm/@cordwainer/cw-elements@1.5.2/cdn/components/avatar-group/avatar-group.js"></script>

To import this component from the CDN using a JavaScript import: 

import 'https://cdn.jsdelivr.net/npm/@cordwainer/cw-elements@1.5.2/cdn/components/avatar-group/avatar-group.js';

To import this component using a bundler:

import '@cordwainer/cw-elements/dist/components/avatar-group/avatar-group.js';

To import this component as a React component:

import CwAvatarGroup from '@cordwainer/cw-elements/dist/react/avatar-group';

Slots

Name Description
(default) One or more <cw-avatar> elements to display.

Learn more about using slots.

Properties

Name Description Reflects Type Default
max The maximum number of avatars to display before collapsing the rest into a ”+N” indicator. Shows all by default. number | undefined -
overlap How much each avatar overlaps the one before it, in pixels. number 16
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Custom Properties

Name Description Default
--cw-avatar-group-ring-color The color of the ring drawn around each avatar so overlapping ones stay visually distinct. Defaults to matching the page/panel background — override this when the group sits on a differently-colored surface. var(–cw-color-neutral-0)

Learn more about customizing CSS custom properties.

Parts

Name Description
base The component’s base wrapper.

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

  • <cw-popup>
  • <cw-tooltip>