AvatarGroup 头像组新
以叠放或网格展示多个头像，并支持溢出计数
用法
import { AvatarGroup, Avatar } from '@heroui/react';组件结构
import { AvatarGroup, Avatar } from '@heroui/react';
export default () => (
<AvatarGroup>
<Avatar>
<Avatar.Image />
<Avatar.Fallback />
</Avatar>
<AvatarGroup.Count /> {/* 可选的显式子组件 */}
</AvatarGroup>
);示例
最大数量
自定义计数
尺寸
网格
叠放样式（Overlap）
自定义样式
Tailwind CSS
全局 CSS
可使用 @layer components 指令自定义 AvatarGroup 组件类。
了解更多。
@layer components {
.avatar-group {
--avatar-group-overlap: 0.75rem;
--avatar-group-seam: 2px;
}
.avatar-group__count {
@apply font-semibold;
}
}样式参考
HeroUI 遵循 BEM 方法论，确保组件变体与状态可复用且易于自定义。
CSS 类
AvatarGroup 组件使用以下 CSS 类（查看源码样式）：
基础类
.avatar-group- 头像组基础容器.avatar-group--grid- 网格布局修饰符（无叠放）.avatar-group--clip- 新月裁切 / 透明缝（默认叠放）.avatar-group--ring- 通过--background的实线 box-shadow 描边.avatar-group__count- 溢出计数头像
叠放布局在兄弟元素之间使用负外边距（--avatar-group-overlap，默认 0.5rem）。clip 模式对非末子头像做遮罩，并光学微调 fallback 字形；ring 模式使用 --background 细线 box-shadow 描边。
API 参考
AvatarGroup
| Prop | 类型 | 默认值 | 描述 |
|---|---|---|---|
size | 'sm' | 'md' | 'lg' | 'md' | 当子 Avatar 未指定 size 时应用到子头像（及溢出计数）；默认与 Avatar 一致 |
color | 'default' | 'accent' | 'success' | 'warning' | 'danger' | - | 当子 Avatar 未指定 color 时，应用到子头像（及溢出计数）的颜色 |
variant | 'default' | 'soft' | - | 当子 Avatar 未指定 variant 时，应用到子头像（及溢出计数）的变体 |
max | number | - | 最多渲染的头像子项数量；省略则显示全部 |
isGrid | boolean | false | 是否使用无叠放的换行网格布局 |
overlap | 'clip' | 'ring' | 'clip' | 叠放样式：新月裁切（默认）或 box-shadow 描边；isGrid 时忽略 |
className | string | - | 附加 CSS 类 |
children | React.ReactNode | - | 要组合的 Avatar 组件（以及可选的 AvatarGroup.Count） |
AvatarGroup.Count
由 Avatar + Avatar.Fallback 组合而成，用于溢出指示。不受 max 截断。
| Prop | 类型 | 默认值 | 描述 |
|---|---|---|---|
children | React.ReactNode | - | 计数内容（例如 +3） |
size | 'sm' | 'md' | 'lg' | - | 覆盖组的尺寸 |
color | 'default' | 'accent' | 'success' | 'warning' | 'danger' | - | 覆盖组的颜色 |
variant | 'default' | 'soft' | - | 覆盖组的变体 |
className | string | - | 附加 CSS 类 |
注意事项
- AvatarGroup 通过 React Context 仅向直接 Avatar 子组件传递
size、color与variant - 设置
max会截断可见头像并根据剩余子项自动计数；省略则显示全部 - 已知总量（例如来自服务端）时，渲染显式的
AvatarGroup.Count— 它不受max截断，并会抑制自动计数。请用Count替代已移除的 v2total isGrid会禁用叠放，改为换行网格布局overlap默认为"clip"（新月裁切）；使用"ring"可改为实线描边；与isGrid同时使用时无效- 默认不加
role="group"— 当叠放有语义（指派人、在看的人）时，自行加上role="group"，并配合aria-label或aria-labelledby
