Avatar Group

v1.0.0-rc.11
@ui5/webcomponents
<ui5-avatar-group>

Avatar Group - type "Individual"

John Doe Software Developer
Woman Avatar 5 Man Avatar 3 Woman Avatar 5 Man Avatar 3 Woman Avatar 5 Man Avatar 3
<ui5-popover header-text="Person Card" class="personPopover" style="width: 300px" placement-type="Bottom" prevent-focus-restore>
	...
	<ui5-avatar id="popAvatar"></ui5-avatar>
	...
</ui5-popover>

<ui5-popover header-text="My people" class="peoplePopover" style="width: 400px" placement-type="Bottom">
	...
	<div class="placeholder" style="display: flex; flex-wrap: wrap;"></div>
	...
</ui5-popover>

<ui5-avatar-group type="Individual">
	<ui5-avatar size="M" icon="employee"></ui5-avatar>
	<ui5-avatar size="M" initials="JD"></ui5-avatar>
	<ui5-avatar size="M">
		<img src="../../../assets/images/avatars/woman_avatar_5.png" alt="Woman Avatar 5">
	</ui5-avatar>
	...
</ui5-avatar-group>

<script>
	const avatarGroup = document.querySelector("ui5-avatar-group");
	const peoplePopover = document.querySelector(".peoplePopover");
	const personPopover = document.querySelector(".personPopover");

	function onAvatarClicked(avatarRef) {
		personPopover.showAt(avatarRef);
	}

	function onButtonClicked(targetRef) {
		let html = "";
		const firstHiddenIndex = avatarGroup.items.length - avatarGroup.hiddenItems.length;

		avatarGroup.hiddenItems.forEach((avatar, index) => {
			html += `<ui5-avatar 
						...
						color-scheme="${avatarGroup.colorScheme[firstHiddenIndex + index]}"
					</ui5-avatar>`;
		});

		placeholder.innerHTML = html;
		peoplePopover.showAt(targetRef);
	}

	avatarGroup.addEventListener("click", function (event) {
		if (event.detail.overflowButtonClicked) {
			onButtonClicked(event.detail.targetRef);
		} else {
			onAvatarClicked(event.detail.targetRef);
		}
	});
</script>
	

Avatar Group - type "Group"

Woman Avatar 5 Man Avatar 3 Woman Avatar 5 Man Avatar 3 Woman Avatar 5 Man Avatar 3
<ui5-popover header-text="My people" class="peoplePopover" style="width: 400px" placement-type="Bottom">
	...
	<div class="placeholder" style="display: flex; flex-wrap: wrap;"></div>
	...
</ui5-popover>

<ui5-avatar-group type="Group">
	<ui5-avatar size="M" icon="employee"></ui5-avatar>
	<ui5-avatar size="M" initials="JD"></ui5-avatar>
	<ui5-avatar size="M">
		<img src="../../../assets/images/avatars/woman_avatar_5.png" alt="Woman Avatar 5">
	</ui5-avatar>
	...
</ui5-avatar-group>

<script>
	const slider = document.querySelector("ui5-slider");

	const avatarGroup = document.querySelector("ui5-avatar-group");
	const peoplePopover = document.querySelector(".peoplePopover");

	function onAvatarGroupClick(targetRef) {
		peoplePopover.showAt(targetRef);
	}

	avatarGroup.addEventListener("click", function (event) {
		onAvatarGroupClick(event.detail.targetRef);
	});
</script>
	

Avatar Group Sizes

Man Avatar 1 Woman Avatar 5 Man Avatar 3
Man Avatar 1 Woman Avatar 5 Man Avatar 3
Man Avatar 1 Woman Avatar 5 Man Avatar 3
<ui5-avatar-group type="Individual">
	<ui5-avatar size="S">
		<img src="../../../assets/images/avatars/man_avatar_1.png" alt="Man Avatar 1">
	</ui5-avatar>
	<ui5-avatar size="S" initials="JD"></ui5-avatar>
	<ui5-avatar size="S">
		<img src="../../../assets/images/avatars/woman_avatar_5.png" alt="Woman Avatar 5">
	</ui5-avatar>
	<ui5-avatar size="S">
		<img src="../../../assets/images/avatars/man_avatar_3.png" alt="Man Avatar 3">
	</ui5-avatar>
</ui5-avatar-group>

<br>

<ui5-avatar-group type="Individual">
	<ui5-avatar size="M">
		<img src="../../../assets/images/avatars/man_avatar_1.png" alt="Man Avatar 1">
	</ui5-avatar>
	<ui5-avatar size="M" initials="JD"></ui5-avatar>
	<ui5-avatar size="M">
		<img src="../../../assets/images/avatars/woman_avatar_5.png" alt="Woman Avatar 5">
	</ui5-avatar>
	<ui5-avatar size="M">
		<img src="../../../assets/images/avatars/man_avatar_3.png" alt="Man Avatar 3">
	</ui5-avatar>
</ui5-avatar-group>

<br>

<ui5-avatar-group type="Group">
	<ui5-avatar size="L">
		<img src="../../../assets/images/avatars/man_avatar_1.png" alt="Man Avatar 1">
	</ui5-avatar>
	<ui5-avatar size="L" initials="JD"></ui5-avatar>
	<ui5-avatar size="L">
		<img src="../../../assets/images/avatars/woman_avatar_5.png" alt="Woman Avatar 5">
	</ui5-avatar>
	<ui5-avatar size="L">
		<img src="../../../assets/images/avatars/man_avatar_3.png" alt="Man Avatar 3">
	</ui5-avatar>
</ui5-avatar-group>
	

Overview

Displays a group of avatars arranged horizontally. It is useful to visually showcase a group of related avatars, such as, project team members or employees. The component allows you to display the avatars in different sizes, depending on your use case. The AvatarGroup component has two group types:
  • Group type: The avatars are displayed as partially overlapped on top of each other and the entire group has one click/tap area.
  • Individual type: The avatars are displayed side-by-side and each avatar has its own click/tap area.

Responsive Behavior

When the available space is less than the width required to display all avatars, an overflow visualization appears as a button placed at the end with the same shape and size as the avatars. The visualization displays the number of avatars that have overflowed and are not currently visible.

Usage

Use the AvatarGroup if:
  • You want to display a group of avatars.
  • You want to display several avatars which have something in common.
Do not use the AvatarGroup if:
  • You want to display a single avatar.
  • You want to display a gallery for simple images.
  • You want to use it for other visual content than avatars.

Keyboard Handling

The component provides advanced keyboard handling. When focused, the user can use the following keyboard shortcuts in order to perform a navigation:
- type Individual:
  • [TAB] - Move focus to the overflow button
  • [LEFT] - Navigate one avatar to the left
  • [RIGHT] - Navigate one avatar to the right
  • [HOME] - Navigate to the first avatar
  • [END] - Navigate to the last avatar
  • [SPACE],[ENTER],[RETURN] - Trigger ui5-click event

- type Group:
  • [TAB] - Move focus to the next interactive element after the component
  • [SPACE],[ENTER],[RETURN] - Trigger ui5-click event

Properties/Attributes

You can use both properties and attributes with the same effect. The name of each attribute is listed below the name of the property, if different.

Name
Type
Default Value
Description
colorScheme (readonly)
color-scheme
AvatarColorScheme [0..n]
[0..n]
Returns an array containing the AvatarColorScheme values that correspond to the avatars in the component.
hiddenItems (readonly)
hidden-items
HTMLElement [0..n]
[0..n]
Returns an array containing the ui5-avatar instances that are currently not displayed due to lack of space.
type
AvatarGroupType
"Group"
Defines the mode of the AvatarGroup.

Available options are:
  • Group
  • Individual

Slots

This Element provides slot(s). This means it can display its child nodes.
Unless targeting the default slot, use the slot attribute to define the destination slot for each child.
Text, along with HTML Elements with no slot attribute, goes the the default slot.

Slot
Type
Description
default
HTMLElement [0..n]
Defines the items of the component. Use the ui5-avatar component as an item.

Note: The UX guidelines recommends using avatars with "Circle" shape. Moreover, if you use avatars with "Square" shape, there will be visual inconsistency as the built-in overflow action has "Circle" shape.
overflowButton
HTMLElement
Defines the overflow button of the component. Note: We recommend using the ui5-button component.

Note: If this slot is not used, the component will display the built-in overflow button.

Events

This Web Component fires semantic events upon user interaction. You can bind to these events with the standard DOM APIs, such as addEventListener.

Name
Description
click
Fired when the component is activated either with a click/tap or by using the Enter or Space key.
since v1.0.0-rc.11
targetRef
type: HTMLElement
description: The DOM ref of the clicked item.
overflowButtonClicked
type: boolean
description: indicates if the overflow button is clicked
overflow
Fired when the count of visible ui5-avatar elements in the component has changed
since v1.0.0-rc.13
Theme: Quartz Light Quartz Dark Quartz High Contrast Black Quartz High Contrast White Belize High Contrast Black High Contrast White Horizon
Content Density: Cozy Compact
Text Direction: LTR RTL
Apply Cancel