AvatarGroupElement

Full API (methods, signatures, descriptions): see api-reference.md. This note covers only behaviour that isn't obvious from the signatures.

Three kinds of avatar live inside one group

<vaadin-avatar-group> renders every avatar client-side, from its items property, into three distinct places:

Avatar	Where it lives	Reached with
A visible one	direct <vaadin-avatar> child, no slot attribute	getAvatars(), getAvatar(index)
The overflow summary (+N)	<vaadin-avatar slot="overflow"> child	getOverflowAvatar()
A hidden one	<vaadin-avatar> inside a <vaadin-avatar-group-menu-item> in the overlay menu	getOverflowAvatars()

All three match a naive vaadin-avatar CSS lookup, because Playwright's CSS selectors pierce the shadow DOM and the overlay menu is a light-DOM child of the group. getAvatarsLocator() therefore uses an explicit xpath=./vaadin-avatar[not(@slot)], which matches direct children only and does not pierce — so the overflow avatar and the menu avatars stay out of getAvatars(), getVisibleCount() and assertNames().

The overflow avatar is always present

It exists even when nothing overflows, and is then marked hidden. Use assertHasOverflow() / assertHasNoOverflow() (the has-overflow attribute on the group) to assert whether anything is actually hidden, rather than testing the overflow avatar's presence.

How many avatars stay visible

maxItemsVisible is a budget for the whole row, overflow avatar included, so a group of five items with setMaxItemsVisible(3) shows two avatars plus the +3 overflow avatar. Values below 2 are clamped: the group always keeps at least two slots.

The count also depends on the available width — the group hides further avatars when they no longer fit. Give the group an explicit width in test views if you want to assert an exact getVisibleCount().

Opening the overflow

The hidden avatars are in the DOM as soon as the group overflows, so assertOverflowNames(...) works either way, but they are only visible while the overlay is open. Like ContextMenuElement, the overlay is driven through the UI rather than a property:

AvatarGroupElement group = AvatarGroupElement.get(page);
group.assertNames("Bob Ross", "Carol Danvers");
group.assertHasOverflow();

group.openOverflow();                       // clicks the +N avatar, waits for open
group.assertOverflowNames("Dana Scully", "Erin Fisher", "Xavier Young");
group.getOverflowAvatars().get(0).assertName("Dana Scully");
group.closeOverflow();                      // Escape, waits for closed

Open state is read from the overflow avatar's aria-expanded attribute, which the component keeps in sync with the overlay. Clicking the +N avatar toggles the overlay, so openOverflow() clicks only when the overlay is closed — calling it twice leaves the overlay open rather than closing it again.