Skip to content

ComponentsIdentity & presence

SourceSource

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.

Root class newt-avatar-group
import { 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

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

PropType
overflow?number

How many members are not shown. Above zero it adds a final "+N" chip.

Typenumber
Default0
size?"sm" | "default" | "lg"

Size of the chip. Give the avatars inside the same size.

Type"sm" | "default" | "lg"
Default"default"
overflowLabel?(count: number) => string

What a screen reader says for the chip.

Type(count: number) => string
Default(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