Skip to content
Nana UI

Data Display & Media

Avatar Group

Several people at once — the tenants of a unit, the people on an approval — as overlapping avatars. Past max, the last seat becomes a count of everyone not shown, so the row never grows past a known width.

View .md Download

max counts the “+N” seat, so the row is never wider than max avatars. Set --nana-avatar-group-ring to the colour behind the group when it sits on anything other than the page surface.

npm install @nana-tec/ui-components

Or copy the source in and own it:

npx @nana-tec/ui add avatar-group --framework web-components
npx @nana-tec/ui add avatar-group --framework svelte

Lands in src/lib/components/ui/avatar-group/ as NanaAvatarGroup.svelte, styled with Tailwind classes that resolve to the design tokens. Requires Tailwind v4.

Import the autoloader once, in your app's entry point. Every <nana-*> tag then works anywhere, and each component downloads only the first time a page uses it:

import "@nana-tec/ui-components/autoloader";
import "@nana-tec/ui-components/theme";

The second line gives every component the Nana look and the design tokens behind it. Leave it out to style the components entirely yourself.

Import a component directly when it must be ready at once: on screen at first paint, or when you call its methods straight away. The two mix freely:

import "@nana-tec/ui-components/avatar-group";

Copied in with npx @nana-tec/ui add avatar-group? Import your project's own @/lib/nana-ui/autoloader.js once instead; the CLI keeps it up to date.

<nana-avatar-group label="Tenants of 4B" max="3">
<nana-avatar name="Kamau Juma"></nana-avatar>
<nana-avatar name="Wanjiru Otieno"></nana-avatar>
<nana-avatar name="Achieng Odhiambo"></nana-avatar>
<nana-avatar name="Mwangi Kariuki"></nana-avatar>
</nana-avatar-group>
<script lang="ts">
import { NanaAvatar } from '$lib/components/ui/avatar';
import { NanaAvatarGroup } from '$lib/components/ui/avatar-group';
let { people } = $props();
</script>
<NanaAvatarGroup items={people} max={4} label="Project team">
{#snippet item(person)}<NanaAvatar name={person.name} src={person.photo} />{/snippet}
</NanaAvatarGroup>

Shows up to max avatars; when there are more, the last place becomes a count of the rest, announced as “3 more”.

Properties

PropertyAttributeTypeDefaultDescription
labellabelstring''Accessible name for the group
maxmaxnumber4The most seats to show, the count included
sizesizeAvatarSize | undefined—Size applied to every avatar

Slots

SlotDescription
(default)The nana-avatar elements

CSS parts

PartDescription
::part(base)The row of avatars
::part(more)The count of people not shown

CSS custom properties

PropertyDescription
--nana-avatar-group-overlapHow far each avatar tucks under the one before
--nana-avatar-group-ringThe colour of the ring that separates them, usually the surface behind
--nana-avatar-sizeWidth and height of the count, to match avatars sized the same way

NanaAvatarGroup

PropTypeDefault
itemsrequiredreadonly T[]
maxnumber4
labelstring''
itemrequiredSnippet<[T]>

Also accepts Omit<HTMLAttributes<HTMLDivElement>, 'class'>.