頭像堆疊 Avatar Stack｜免費 React 元件

一排重疊的圓形頭像，hover/focus 時上浮放大、鄰居讓開並浮出名字 tooltip。

把這個效果裝進你的專案

在專案資料夾執行指令，CLI 會加入原始碼與依賴套件，再依下方使用範例引用元件。

npx webberui@latest add avatar-stack

Avatar Stack 是用 React、Motion（motion/react）與 Tailwind CSS 做的頭像堆疊（avatar group／疊放頭像）元件：頭像左壓右重疊排列，滑鼠移上或鍵盤聚焦時該頭像上浮放大、左右鄰居讓開，並浮出名字。超過 max 的人數會收成 +N 泡泡，沒有圖片時用名字產生固定的漸層底色與首字。

Playground

即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。

最多顯示數量max

頭像尺寸（px）size

import * as React from "react";

export default function Example() {
  return (
    <div className="flex min-h-[320px] w-full items-center justify-center p-6">

編輯中的呼叫預設屬性

<AvatarStack/>

    </div>
  );
}

完整範例包含預覽的排版與資料。先安裝元件，再把範例檔貼入你的專案。

適用情境

協作工具顯示「目前正在檢視這份文件的人」
專案卡片或任務列上列出負責成員
活動或課程頁面呈現「已有 N 人報名」並露出部分頭像
首頁 hero 區的社群證明，搭配「超過一萬名團隊使用」之類的文案
不適合：要完整展示成員姓名、職稱與照片時，改用 Team Grid Section

安裝

npx webberui@latest add https://webberui.com/r/avatar-stack.json

或在 components.json 設定 registries 後，改用 @webberui/avatar-stack 安裝。

使用

import { AvatarStack } from "@/components/ui/avatar-stack";

<AvatarStack
  avatars={[
    { src: "/team/ada.jpg", alt: "Ada Lovelace" },
    { alt: "Alan Turing" },
    { alt: "Grace Hopper", fallback: "GH" },
  ]}
  max={5}
  size={40}
/>;

範例

中文姓名的文字頭像

沒有 src 時會取 alt 的第一個字元當頭像文字，中文名字就會顯示姓氏。底色由名字計算，同一個人每次顏色都一樣。

import { AvatarStack } from "@/components/ui/avatar-stack";

<AvatarStack
  avatars={[
    { alt: "王小明" },
    { alt: "林怡君" },
    { alt: "陳志豪" },
    { alt: "張雅婷" },
  ]}
  size={36}
/>;

文件卡片上的共同編輯者

縮小 size、把 max 設小一點，適合放在卡片角落；其餘人數會顯示為 +N。

<div className="flex items-center justify-between rounded-xl border p-4">
  <div>
    <p className="text-sm font-medium">2026 Q4 產品規劃</p>
    <p className="text-xs text-neutral-500">10 分鐘前更新</p>
  </div>
  <AvatarStack avatars={editors} max={3} size={28} />
</div>

從 API 轉換資料

把後端的使用者資料轉成 AvatarStackItem，型別可以直接 import。

import { AvatarStack, type AvatarStackItem } from "@/components/ui/avatar-stack";

type Member = { id: string; name: string; avatarUrl: string | null };

function MemberAvatars({ members }: { members: Member[] }) {
  const avatars: AvatarStackItem[] = members.map((m) => ({
    src: m.avatarUrl ?? undefined,
    alt: m.name,
  }));
  return <AvatarStack avatars={avatars} max={4} />;
}

Props

Prop	型別	預設值	說明
`avatars`	`AvatarStackItem[]`	—	頭像清單，依序由左至右堆疊（左壓右）
`max`	`number`	`5`	最多顯示幾個頭像，其餘彙整成 +N 泡泡
`size`	`number`	`40`	頭像直徑（px）
`className`	`string`	—	外層容器自訂樣式

AvatarStackItem

欄位	型別	說明
`src`	`string?`	頭像圖片網址；省略時顯示文字 fallback
`alt`	`string`	替代文字，同時作為 tooltip 顯示的名字
`fallback`	`string?`	無圖片時顯示的字元；省略時自動取 `alt` 首字