Avatar Group
A row of overlapping avatars with a count for the members not shown.
Use it to say “these people, and some more” in little room: who is in a voice channel, who reacted, who is typing. Show three to five avatars and put the rest in the count.
The count is a prop and not derived from the children, because the total usually comes from the server while only the first few members are loaded.
newt-avatar-groupimport { Avatar } from "@/registry/bases/newt/ui/avatar"
import { AvatarGroup } from "@/registry/bases/newt/ui/avatar-group"
export default function AvatarGroupDemo() {
return (
<div className="flex items-center gap-3 rounded-md bg-newt-bg-surface px-4 py-3">
<AvatarGroup size="sm" overflow={2} aria-label="In voice: 5 members">
<Avatar size="sm">A</Avatar>
<Avatar size="sm" className="bg-newt-online">
K
</Avatar>
<Avatar size="sm" className="bg-newt-danger">
M
</Avatar>
</AvatarGroup>
<span className="text-sm text-newt-text-secondary">5 in Lounge</span>
</div>
)
}<script setup lang="ts">
import { Avatar } from "~~/registry/bases/newt/ui/avatar"
import { AvatarGroup } from "~~/registry/bases/newt/ui/avatar-group"
</script>
<template>
<div class="flex items-center gap-3 rounded-md bg-newt-bg-surface px-4 py-3">
<AvatarGroup size="sm" :overflow="2" aria-label="In voice: 5 members">
<Avatar size="sm">A</Avatar>
<Avatar size="sm" class="bg-newt-online">K</Avatar>
<Avatar size="sm" class="bg-newt-danger">M</Avatar>
</AvatarGroup>
<span class="text-sm text-newt-text-secondary">5 in Lounge</span>
</div>
</template>Installation
npx newtui@latest add avatar-groupnpx shadcn@latest add @newtui/avatar-groupnpx shadcn-vue@latest add @newtui/avatar-grouppnpm dlx newtui@latest add avatar-grouppnpm dlx shadcn@latest add @newtui/avatar-grouppnpm dlx shadcn-vue@latest add @newtui/avatar-groupyarn dlx newtui@latest add avatar-groupyarn dlx shadcn@latest add @newtui/avatar-groupyarn dlx shadcn-vue@latest add @newtui/avatar-groupbunx newtui@latest add avatar-groupbunx shadcn@latest add @newtui/avatar-groupbunx shadcn-vue@latest add @newtui/avatar-groupdeno run -A npm:newtui@latest add avatar-groupdeno run -A npm:shadcn@latest add @newtui/avatar-groupdeno run -A npm:shadcn-vue@latest add @newtui/avatar-groupvlx newtui@latest add avatar-groupvlx shadcn@latest add @newtui/avatar-groupvlx shadcn-vue@latest add @newtui/avatar-groupvp dlx newtui@latest add avatar-groupvp dlx shadcn@latest add @newtui/avatar-groupvp dlx shadcn-vue@latest add @newtui/avatar-groupnubx newtui@latest add avatar-groupnubx shadcn@latest add @newtui/avatar-groupnubx shadcn-vue@latest add @newtui/avatar-groupnlx newtui@latest add avatar-groupnlx shadcn@latest add @newtui/avatar-groupnlx shadcn-vue@latest add @newtui/avatar-groupupx newtui@latest add avatar-groupupx shadcn@latest add @newtui/avatar-groupupx shadcn-vue@latest add @newtui/avatar-group- newtui
- shadcn
- npm
- pnpm
- yarn
- bun
- deno
- vlt
- vp
- nub
- ni
- upm
The shadcn CLI needs the @newtui registry in your components.json. Set it up.
Add the components it builds on
Copy the source into your project
"use client"
import type { VariantProps } from "class-variance-authority"
import * as React from "react"
import { cn } from "@/lib/utils"
import { avatarVariants } from "@/registry/bases/newt/ui/avatar"
export interface AvatarGroupProps
extends React.ComponentProps<"div">, VariantProps<typeof avatarVariants> {
/**
* How many members are not shown. A count above zero adds a final "+N"
* chip; the total usually comes from the server, not from the children.
*/
overflow?: number
/** What a screen reader says for the chip. */
overflowLabel?: (count: number) => string
}
const defaultOverflowLabel = (count: number) => `${count} more`
/*
* A few avatars, overlapped, and a count for the rest. Each one is ringed in
* the colour of the surface behind it so the overlap reads as a cut-out; set
* `--newt-avatar-group-ring` when the group sits on something other than the
* default surface. `size` is the chip's size: give the avatars the same one.
*/
const AvatarGroup = React.forwardRef<HTMLDivElement, AvatarGroupProps>(
(
{
className,
size,
overflow = 0,
overflowLabel = defaultOverflowLabel,
children,
...props
},
ref
) => (
<div
ref={ref}
role="group"
className={cn(
"inline-flex items-center [&>*:not(:first-child)]:-ms-2 [&>*]:shadow-[0_0_0_2px_var(--newt-avatar-group-ring,var(--newt-bg-surface))]",
className
)}
{...props}
>
{children}
{overflow > 0 ? (
<div
className={cn(
avatarVariants({ size }),
"bg-newt-bg-active tabular-nums text-newt-text-primary"
)}
>
<span aria-hidden="true">+{overflow}</span>
<span className="sr-only">{overflowLabel(overflow)}</span>
</div>
) : null}
</div>
)
)
AvatarGroup.displayName = "AvatarGroup"
export { AvatarGroup }<script setup lang="ts">
import type { HTMLAttributes } from "vue"
import {
avatarVariants,
type AvatarVariants,
} from "~~/registry/bases/newt/ui/avatar"
import { cn } from "@/lib/utils"
/*
* A few avatars, overlapped, and a count for the rest. Each one is ringed in
* the colour of the surface behind it so the overlap reads as a cut-out; set
* `--newt-avatar-group-ring` when the group sits on something other than the
* default surface. `size` is the chip's size: give the avatars the same one.
*/
const props = withDefaults(
defineProps<{
class?: HTMLAttributes["class"]
size?: AvatarVariants["size"]
/**
* How many members are not shown. A count above zero adds a final "+N"
* chip; the total usually comes from the server, not from the slot.
*/
overflow?: number
/** What a screen reader says for the chip. */
overflowLabel?: (count: number) => string
}>(),
{ overflow: 0, overflowLabel: (count: number) => `${count} more` }
)
</script>
<template>
<div
role="group"
:class="
cn(
'inline-flex items-center [&>*:not(:first-child)]:-ms-2 [&>*]:shadow-[0_0_0_2px_var(--newt-avatar-group-ring,var(--newt-bg-surface))]',
props.class
)
"
>
<slot />
<div
v-if="props.overflow > 0"
:class="
cn(
avatarVariants({ size: props.size }),
'bg-newt-bg-active tabular-nums text-newt-text-primary'
)
"
>
<span aria-hidden="true">+{{ props.overflow }}</span>
<span class="sr-only">{{ props.overflowLabel(props.overflow) }}</span>
</div>
</div>
</template>export { default as AvatarGroup } from "./AvatarGroup.vue"Update the import paths
The files import @/lib/utils and sibling components through the aliases in your components.json. Point them at wherever those live in your project.
No CLI, no components.json: paste this into Claude, Cursor, Copilot or any coding assistant and it adds Avatar Group to your React project by hand. The prompt carries the source of every file the CLI would write — this component's and those of the components it builds on — with the imports already pointed at the default aliases.
No CLI, no components.json: paste this into Claude, Cursor, Copilot or any coding assistant and it adds Avatar Group to your Vue project by hand. The prompt carries the source of every file the CLI would write — this component's and those of the components it builds on — with the imports already pointed at the default aliases.
Usage
import { AvatarGroup } from "@/components/ui/avatar-group"
export function Example() {
return <AvatarGroup />
}<script setup lang="ts">
import { AvatarGroup } from "@/components/ui/avatar-group"
</script>
<template>
<AvatarGroup />
</template>API reference
AvatarGroup
overflow?number
How many members are not shown. Above zero it adds a final "+N" chip.
number0size?"sm" | "default" | "lg"
Size of the chip. Give the avatars inside the same size.
"sm" | "default" | "lg""default"overflowLabel?(count: number) => string
What a screen reader says for the chip.
(count: number) => string(count) => `${count} more`Each avatar is ringed in the colour of the surface behind it, so the overlap reads as a cut-out. The ring defaults to --newt-bg-surface; on another background set --newt-avatar-group-ring on the group or any ancestor.
Accessibility
The group is a role="group" and needs a name that says what the people have in common: pass aria-label, such as “In voice: 5 members”. Initials alone do not identify anybody, so give each avatar an accessible name when who they are matters, or list the names in the label. The chip shows “+2” and is read as “2 more”.
overflowLabel builds the name of the +N chip. Translating labels lists every English default.
Tokens
Avatar Group reads its colours, radii and motion from the --newt-* tokens installed with the library. Override a token and every component that reads it follows, including this one — see the token layer. In the plain HTML and CSS distribution the same component is newt-avatar-group.
--newt-bg-surface--newt-bg-active--newt-text-primary