AvatarGroup

View source on GitHub

AvatarGroup is used to both display a group of user avatars and, optionally, control actions related to the users group.

Props

Component props
Name	Type	Default
`accessibilityLabel` Required	`string`	-
	Label for screen readers to announce AvatarGroup. See the Accessibility guidelines for details on proper usage.
`collaborators` Required	`$ReadOnlyArray<{\| name: string, src?: string, \|}>`	-
	The user group data. See the collaborators display variant to learn more.
`accessibilityControls`	`string`	-
	Specify the `id` of an associated element (or elements) whose contents or visibility are controlled by a component so that screen reader users can identify the relationship between elements. Optional with button-role component. See the Accessibility guidelines for details on proper usage.
`accessibilityExpanded`	`boolean`	-
	Indicate that a component hides or exposes collapsible components and expose whether they are currently expanded or collapsed. Optional with button-role component. See the Accessibility guidelines for details on proper usage.
`accessibilityHaspopup`	`boolean`	-
	Indicate that a component controls the appearance of interactive popup elements, such as menu or dialog. Optional with button-role component. See the Accessibility guidelines for details on proper usage.
`addCollaborators`	`boolean`	-
	When supplied, it appends an `add` icon to the avatar pile as a call to action to the user. See Best Practices for more info.
`href`	`string`	-
	When supplied, wraps the component in a link, and directs users to the url when item is selected. See the role variant to learn more.
`onClick`	`OnTapType`	-
	Callback fired when the component is clicked (pressed and released) with a mouse or keyboard. See the role variant to learn more and see TapArea's `onTap` for more info about `OnTapType`.
`ref`	`HTMLDivElement \| HTMLAnchorElement`	-
	Forward the ref to the underlying div or anchor element. See the role variant to learn more.
`role`	`"link" \| "button"`	-
	Allows user interaction with the component. See the role variant to learn more.
`size`	`"xs" \| "sm" \| "md" \| "fit"`	`"fit"`
	The maximum height of AvatarGroup. If size is `fit`, AvatarGroup will fill 100% of the parent container width. See the fixed size and responsive size variant to learn more.

Usage guidelines

When to Use

For the general display of groups of people, companies and/or brands.
In cases where an affordance for adding collaborators is needed.

When Not to Use

Displaying a group of people, companies and/or brands in a square format. Use AvatarPair instead.

Best Practices

Use the default alternative if no image source is available. This should be the first character of the provided name.

Don't

Use alternative graphics or icons

Use AvatarGroup to represent a group of people and/or organizations.

Don't

Use AvatarGroup to represent metaphorical ideas, like multiple Boards or trends. Instead, consider an Image or the appropriate interactive component.

Accessibility

ARIA attributes

AvatarGroup requires accessibilityLabel. AvatarGroup is a group of elements that require a parent label describing both the data presented and the call to action in the case of button and link roles. As seen in the example below, the screen-reader reads: "Collaborators: Keerthi, Alberto, and 10 more. Add collaborators to this board."

If AvatarGroup is used as a control button to show/hide Popover-component, we recommend passing the following ARIA attributes to assist screen readers:

accessibilityControls: informs the screen reader that AvatarGroup controls the display of an anchored Popover-component. It populates aria-controls.
accessibilityHaspopup: informs the screen reader that there’s a Popover-component attached to AvatarGroup. It populates aria-haspopup.
accessibilityExpanded: informs the screen reader whether an anchored Popover-component is currently open or closed. It populates aria-expanded.

function Example() {
  const [open, setOpen] = React.useState(false);
  const [selectedBoard, setSelectedBoard] = React.useState('Fashion');
  const anchorRef = React.useRef();

  const SearchCollaboratorsField = () => {
    const ref = React.useRef();

    React.useEffect(() => {
      ref.current.focus();
    }, []);

    return (
      <SearchField
        accessibilityLabel="Search other users"
        id="searchField"
        onChange={() => {}}
        placeholder="Search by name or email"
        size="lg"
        ref={ref}
      />
    )
  }

  return (
    <React.Fragment>
      <AvatarGroup
        accessibilityLabel="Collaborators: Keerthi, Alberto, and 10 more. Add collaborators to this board."
        accessibilityExpanded={open}
        addCollaborators
        role="button"
        onClick={() => setOpen( open => !open)}
        ref={anchorRef}
        size="md"
        collaborators={[

          {
            name: 'Keerthi',
            src: 'https://i.ibb.co/ZfCZrY8/keerthi.jpg',
          },
          {
            name: 'Alberto',
            src: 'https://i.ibb.co/NsK2w5y/Alberto.jpg',
          },
          ...new Array(10),
        ]}
        />
      {open && (
        <Layer>
          <Popover
            anchor={anchorRef.current}
            idealDirection="down"
            onDismiss={() => setOpen(false)}
            positionRelativeToAnchor={false}
            size="xl"
          >
            <Box
              flex="grow"
              marginEnd={4}
              marginStart={4}
              marginTop={6}
              marginBottom={8}
              width={360}
            >
              <Flex direction="column" gap={6}>
                <Text align="center" color="darkGray" weight="bold">
                  Invite collaborators
                </Text>
                <SearchCollaboratorsField />
              </Flex>
            </Box>
          </Popover>
        </Layer>
      )}
    </React.Fragment>
  );
}

function Example() {
  const [open, setOpen] = React.useState(false);
  const [selectedBoard, setSelectedBoard] = React.useState('Fashion');
  const anchorRef = React.useRef();

  const SearchCollaboratorsField = () => {
    const ref = React.useRef();

    React.useEffect(() => {
      ref.current.focus();
    }, []);

    return (
      <SearchField
        accessibilityLabel="Search other users"
        id="searchField"
        onChange={() => {}}
        placeholder="Search by name or email"
        size="lg"
        ref={ref}
      />
    )
  }

  return (
    <React.Fragment>
      <AvatarGroup
        accessibilityLabel="Collaborators: Keerthi, Alberto, and 10 more. Add collaborators to this board."
        accessibilityExpanded={open}
        addCollaborators
        role="button"
        onClick={() => setOpen( open => !open)}
        ref={anchorRef}
        size="md"
        collaborators={[

          {
            name: 'Keerthi',
            src: 'https://i.ibb.co/ZfCZrY8/keerthi.jpg',
          },
          {
            name: 'Alberto',
            src: 'https://i.ibb.co/NsK2w5y/Alberto.jpg',
          },
          ...new Array(10),
        ]}
        />
      {open && (
        <Layer>
          <Popover
            anchor={anchorRef.current}
            idealDirection="down"
            onDismiss={() => setOpen(false)}
            positionRelativeToAnchor={false}
            size="xl"
          >
            <Box
              flex="grow"
              marginEnd={4}
              marginStart={4}
              marginTop={6}
              marginBottom={8}
              width={360}
            >
              <Flex direction="column" gap={6}>
                <Text align="center" color="darkGray" weight="bold">
                  Invite collaborators
                </Text>
                <SearchCollaboratorsField />
              </Flex>
            </Box>
          </Popover>
        </Layer>
      )}
    </React.Fragment>
  );
}

Keyboard Interaction

If AvatarGroup is acting as a button or link, the Tab key will focus the AvatarGroup.
Hitting the Enter or Return key opens a dialog or redirects to a new page (depending on the role) and the user can then add or view collaborators.

Localization

Be sure to localize accessibilityLabel.

Variants

Fixed sizes

AvatarGroup is available in 3 fixed height sizes: xs (24px), sm (32px), and md (48px).

size="xs"

size="sm"

size="md"

Responsive sizing

AvatarGroup is a responsive component. Avatar Groups that are not given a size prop or use size fit will expand to fit to the width of their parent container. A common use case is to achieve column-based sizing. Resize the width or number of avatars to see the AvatarGroup change to match the width of the Column it's been placed in.

<Box width={600} height={100}>
  <Flex>
    <Box column={5}>
      <AvatarGroup
        accessibilityLabel="Collaborators: Keerthi, Alberto, and Shanice."
        size="fit"
        collaborators={[
          {
            name: 'Keerthi',
            src: 'https://i.ibb.co/ZfCZrY8/keerthi.jpg',
          },
          {
            name: 'Alberto',
            src: 'https://i.ibb.co/NsK2w5y/Alberto.jpg',
          },
            {
            name: 'Shanice',
            src: 'https://i.ibb.co/7tGKGvb/shanice.jpg',
          },
        ]}
      />
    </Box>
    <Box column={7} marginStart={2} height="100%">
      <Text inline >The </Text>
      <Text inline weight="bold">
        <Link inline href="https://www.pinterest.com/search/boards/?q=quick%20vegan%20recipes&rs=typed&term_meta[]=quick%7Ctyped&term_meta[]=vegan%7Ctyped&term_meta[]=recipes%7Ctyped">Quick Vegan Recipes </Link>
      </Text>
      <Text inline> board has 3 followers.</Text>
    </Box>
  </Flex>
</Box>

<Box width={600} height={100}>
  <Flex>
    <Box column={5}>
      <AvatarGroup
        accessibilityLabel="Collaborators: Keerthi, Alberto, and Shanice."
        size="fit"
        collaborators={[
          {
            name: 'Keerthi',
            src: 'https://i.ibb.co/ZfCZrY8/keerthi.jpg',
          },
          {
            name: 'Alberto',
            src: 'https://i.ibb.co/NsK2w5y/Alberto.jpg',
          },
            {
            name: 'Shanice',
            src: 'https://i.ibb.co/7tGKGvb/shanice.jpg',
          },
        ]}
      />
    </Box>
    <Box column={7} marginStart={2} height="100%">
      <Text inline >The </Text>
      <Text inline weight="bold">
        <Link inline href="https://www.pinterest.com/search/boards/?q=quick%20vegan%20recipes&rs=typed&term_meta[]=quick%7Ctyped&term_meta[]=vegan%7Ctyped&term_meta[]=recipes%7Ctyped">Quick Vegan Recipes </Link>
      </Text>
      <Text inline> board has 3 followers.</Text>
    </Box>
  </Flex>
</Box>

Collaborators display

AvatarGroup displays up to three user avatars. More users, if present, will be displayed as a numerical count for the md and fit sizes.

Role

AvatarGroup can be display only, but can also act as a button or link. It will only be clickable if role is set to button or link. For button role, onClick is required. For link role, href is required.

function ButtonExample() {
  const [open, setOpen] = React.useState(false);
  const [selectedBoard, setSelectedBoard] = React.useState('Fashion');
  const anchorRef = React.useRef();
  const collaborators = [
    {
      name: 'Keerthi',
      src: 'https://i.ibb.co/ZfCZrY8/keerthi.jpg',
    }, {
      name: 'Alberto',
      src: 'https://i.ibb.co/NsK2w5y/Alberto.jpg',
    }, {
      name: 'Shanice',
      src: 'https://i.ibb.co/7tGKGvb/shanice.jpg',
    }
  ];

const List = () => (
  <Flex direction="column" gap={2}>
    {collaborators.map(({ name, src }, index) => (
      <Flex key={index} alignItems="center" gap={2}>
        <Avatar size="md" name={name} src={src} />
        <Text weight="bold">{name}</Text>
      </Flex>
    ))}
  </Flex>
);

  return (
    <React.Fragment>
      <AvatarGroup
        accessibilityLabel="Click to see group collaborators."
        role="button"
        onClick={() => setOpen( open => !open)}
        ref={anchorRef}
        size="md"
        collaborators={collaborators}
        />
      {open && (
        <Layer>
          <Popover
            anchor={anchorRef.current}
            idealDirection="down"
            onDismiss={() => setOpen(false)}
            positionRelativeToAnchor={false}
            size="xs"
          >
            <Box
              flex="grow"
              marginEnd={4}
              marginStart={4}
              marginTop={6}
              marginBottom={8}
              width={360}
            >
              <Flex direction="column" gap={6}>
                <Text align="center" color="darkGray" weight="bold">
                  Collaborators
                </Text>
                <List />
              </Flex>
            </Box>
          </Popover>
        </Layer>
      )}
    </React.Fragment>
  );
}

function ButtonExample() {
  const [open, setOpen] = React.useState(false);
  const [selectedBoard, setSelectedBoard] = React.useState('Fashion');
  const anchorRef = React.useRef();
  const collaborators = [
    {
      name: 'Keerthi',
      src: 'https://i.ibb.co/ZfCZrY8/keerthi.jpg',
    }, {
      name: 'Alberto',
      src: 'https://i.ibb.co/NsK2w5y/Alberto.jpg',
    }, {
      name: 'Shanice',
      src: 'https://i.ibb.co/7tGKGvb/shanice.jpg',
    }
  ];

const List = () => (
  <Flex direction="column" gap={2}>
    {collaborators.map(({ name, src }, index) => (
      <Flex key={index} alignItems="center" gap={2}>
        <Avatar size="md" name={name} src={src} />
        <Text weight="bold">{name}</Text>
      </Flex>
    ))}
  </Flex>
);

  return (
    <React.Fragment>
      <AvatarGroup
        accessibilityLabel="Click to see group collaborators."
        role="button"
        onClick={() => setOpen( open => !open)}
        ref={anchorRef}
        size="md"
        collaborators={collaborators}
        />
      {open && (
        <Layer>
          <Popover
            anchor={anchorRef.current}
            idealDirection="down"
            onDismiss={() => setOpen(false)}
            positionRelativeToAnchor={false}
            size="xs"
          >
            <Box
              flex="grow"
              marginEnd={4}
              marginStart={4}
              marginTop={6}
              marginBottom={8}
              width={360}
            >
              <Flex direction="column" gap={6}>
                <Text align="center" color="darkGray" weight="bold">
                  Collaborators
                </Text>
                <List />
              </Flex>
            </Box>
          </Popover>
        </Layer>
      )}
    </React.Fragment>
  );
}

role="button"

function LinkExample() {
  const [open, setOpen] = React.useState(false);
  const [selectedBoard, setSelectedBoard] = React.useState('Fashion');
  const collaborators = [
    {
      name: 'Keerthi',
      src: 'https://i.ibb.co/ZfCZrY8/keerthi.jpg',
    }, {
      name: 'Alberto',
      src: 'https://i.ibb.co/NsK2w5y/Alberto.jpg',
    }, {
      name: 'Shanice',
      src: 'https://i.ibb.co/7tGKGvb/shanice.jpg',
    }
  ];

  return (
    <AvatarGroup
      accessibilityLabel="Visit group activity board."
      role="link"
      onClick={() => setOpen( open => !open)}
      size="md"
      collaborators={collaborators}
      href="#Role"
      />
  );
}

function LinkExample() {
  const [open, setOpen] = React.useState(false);
  const [selectedBoard, setSelectedBoard] = React.useState('Fashion');
  const collaborators = [
    {
      name: 'Keerthi',
      src: 'https://i.ibb.co/ZfCZrY8/keerthi.jpg',
    }, {
      name: 'Alberto',
      src: 'https://i.ibb.co/NsK2w5y/Alberto.jpg',
    }, {
      name: 'Shanice',
      src: 'https://i.ibb.co/7tGKGvb/shanice.jpg',
    }
  ];

  return (
    <AvatarGroup
      accessibilityLabel="Visit group activity board."
      role="link"
      onClick={() => setOpen( open => !open)}
      size="md"
      collaborators={collaborators}
      href="#Role"
      />
  );
}

role="link"

Avatar
Avatar is the ideal component in cases where only one person or brand needs to be displayed.

AvatarPair
AvatarPair is the ideal solution when you wish to communicate a group of people/brands (ideally two) laid out in a square format.

Edit page on GitHub