Avatar Group

v1.0.0-rc.11

@ui5/webcomponents

<ui5-avatar-group>

Avatar Group - type "Individual"

John Doe

Software Developer

<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"

<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

<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:

Morning Horizon (Light)

Evening Horizon (Dark)

Horizon High Contrast Black

Horizon High Contrast White

Quartz Light

Quartz Dark

Quartz High Contrast Black

Quartz High Contrast White

Content Density:

Cozy

Compact

Text Direction:

LTR

RTL

Apply

Cancel