Avatar Stack
一排重疊的圓形頭像，hover/focus 時上浮放大、鄰居讓開並浮出名字 tooltip。
載入預覽⋯
Playground
即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。
5
40
<AvatarStack />
安裝
npx shadcn@latest add https://webberui.com/r/avatar-stack.json或在 components.json 設定 registries 後，改用 @webberui/avatar-stack 安裝。
安裝依賴後，從 registry JSON（/r/avatar-stack.json 的 files[0].content）複製 avatar-stack.tsx 原始碼到你的 components/ui/ 目錄：
npm install motion clsx tailwind-merge使用
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}
/>;Props
| Prop | 型別 | 預設值 | 說明 |
|---|---|---|---|
avatars | AvatarStackItem[] | — | 頭像清單，依序由左至右堆疊（左壓右） |
max | number | 5 | 最多顯示幾個頭像，其餘彙整成 +N 泡泡 |
size | number | 40 | 頭像直徑（px） |
className | string | — | 外層容器自訂樣式 |
AvatarStackItem
| 欄位 | 型別 | 說明 |
|---|---|---|
src | string? | 頭像圖片網址；省略時顯示文字 fallback |
alt | string | 替代文字，同時作為 tooltip 顯示的名字 |
fallback | string? | 無圖片時顯示的字元；省略時自動取 alt 首字 |
細節
- 頭像以負 margin 重疊，左側壓在右側之上（
z-index由左至右遞減）。 - hover 或鍵盤 focus 任一頭像時，該頭像上浮放大並取得最高層級，左右鄰居往兩側讓開，同時於上方浮出名字 tooltip。
- 無圖片時以名字產生穩定漸層底色並顯示首字，同一名字每次結果都相同。
- 超過
max的頭像數量會彙整成+N泡泡，接在可見頭像之後。
可及性
- 每個頭像為
button並帶aria-label（名字），可用鍵盤 Tab 聚焦，focus 時與 hover 一樣顯示 tooltip。 - tooltip 為純視覺（
aria-hidden），名字已透過aria-label提供給輔助科技，避免重複朗讀。 +N泡泡帶role="img"與aria-label（如「還有 2 位成員」）。- 使用者系統開啟「減少動態效果」時，停用上浮、放大與位移，tooltip 仍會顯示。