> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/components/avatar.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt.

# AvatarGroup 头像组

成组展示成员头像，支持文字头像与人数折叠。使用 `Avatar` 定义每个成员。


## 基础用法

将成员头像放入 `AvatarGroup`，通过每个 `Avatar` 的 `alt` 提供成员名称。


ABCDE

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/avatar/basic.tsx"
import { Avatar, AvatarGroup } from '@ifhover/leaf-ui';

export function AvatarBasic() {
  return (
    <AvatarGroup aria-label="团队成员">
      {['Ada', 'Ben', 'Cara', 'Dan', 'Eva'].map((name) => (
        <Avatar key={name} alt={name}>
          {name.slice(0, 1)}
        </Avatar>
      ))}
    </AvatarGroup>
  );
}
```

展开代码

组内文字头像的颜色用于区分成员，不表示状态。


## 示例

### 尺寸

通过 `AvatarGroup.size` 统一设置组内头像尺寸。


小

ABC

中

ABC

大

ABC

sizes.tsx

复制代码

```tsx lineNumbers file="../../src/examples/avatar/sizes.tsx"
import { Avatar, AvatarGroup, Flex, Grid, Text } from '@ifhover/leaf-ui';
import { Fragment } from 'react';

const sizes = [
  { value: 'sm', label: '小' },
  { value: 'md', label: '中' },
  { value: 'lg', label: '大' },
] as const;

export function AvatarSizes() {
  return (
    <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
      {sizes.map(({ value, label }) => (
        <Fragment key={value}>
          <Text tone="muted">{label}</Text>
          <Flex align="center" wrap>
            <AvatarGroup size={value} aria-label={`${label}号团队成员头像`}>
              {['Ada', 'Ben', 'Cara'].map((name) => (
                <Avatar key={name} alt={name}>
                  {name.slice(0, 1)}
                </Avatar>
              ))}
            </AvatarGroup>
          </Flex>
        </Fragment>
      ))}
    </Grid>
  );
}
```

展开代码

### 图片头像

通过 `alt` 为头像提供成员名称；只显示首字母时，也应提供完整名称。


![](data:image/svg+xml;charset=utf-8,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%20100%20100%22%3E%3Ctitle%3EAlex%20avatar%20illustration%3C%2Ftitle%3E%3Crect%20width%3D%22100%22%20height%3D%22100%22%20fill%3D%22%23e8efe8%22%2F%3E%3Cpath%20d%3D%22M8%20100c2-27%2017-42%2042-42s40%2015%2042%2042%22%20fill%3D%22%2332744d%22%2F%3E%3Cpath%20d%3D%22M36%2062h28l-4%2014-10%207-10-7z%22%20fill%3D%22%23e5af85%22%2F%3E%3Cellipse%20cx%3D%2250%22%20cy%3D%2240%22%20rx%3D%2222%22%20ry%3D%2227%22%20fill%3D%22%23edc3a0%22%2F%3E%3Cpath%20d%3D%22M27%2044c-8-30%208-38%2023-38%2023%200%2030%2022%2023%2041l-6-16-5-9c-9%2010-20%2014-31%2014z%22%20fill%3D%22%232e3c31%22%2F%3E%3Cpath%20d%3D%22M43%2054q7%205%2014%200%22%20fill%3D%22none%22%20stroke%3D%22%23b1775a%22%20stroke-width%3D%222%22%20stroke-linecap%3D%22round%22%2F%3E%3C%2Fsvg%3E)

image.tsx

复制代码

```tsx lineNumbers file="../../src/examples/avatar/image.tsx"
import { Avatar } from '@ifhover/leaf-ui';

const portrait = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(
  '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><title>Alex avatar illustration</title><rect width="100" height="100" fill="#e8efe8"/><path d="M8 100c2-27 17-42 42-42s40 15 42 42" fill="#32744d"/><path d="M36 62h28l-4 14-10 7-10-7z" fill="#e5af85"/><ellipse cx="50" cy="40" rx="22" ry="27" fill="#edc3a0"/><path d="M27 44c-8-30 8-38 23-38 23 0 30 22 23 41l-6-16-5-9c-9 10-20 14-31 14z" fill="#2e3c31"/><path d="M43 54q7 5 14 0" fill="none" stroke="#b1775a" stroke-width="2" stroke-linecap="round"/></svg>',
)}`;

export function AvatarImage() {
  return <Avatar src={portrait} alt="Alex" />;
}
```

展开代码

### 加载失败与默认头像

图片加载失败时显示 `children`、`icon` 或默认图标。更换图片地址后会重试加载。


文字回退

AL![](data:image/png;base64,broken)

默认图标

fallback.tsx

复制代码

```tsx lineNumbers file="../../src/examples/avatar/fallback.tsx"
import { Avatar, Flex, Grid, Text } from '@ifhover/leaf-ui';

export function AvatarFallback() {
  return (
    <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
      <Text tone="muted">文字回退</Text>
      <Flex align="center" wrap>
        <Avatar src="data:image/png;base64,broken" alt="Alex">
          AL
        </Avatar>
      </Flex>
      <Text tone="muted">默认图标</Text>
      <Flex align="center" wrap>
        <Avatar alt="访客" />
      </Flex>
    </Grid>
  );
}
```

展开代码

### 头像组折叠

设置 `maxCount` 限制可见成员数量，通过 `+N` 查看其余成员。


ABC+2

extensions.tsx

复制代码

```tsx lineNumbers file="../../src/examples/avatar/extensions.tsx"
import { Avatar, AvatarGroup } from '@ifhover/leaf-ui';

export function ExtensionDemo() {
  return (
    <AvatarGroup maxCount={3} aria-label="团队成员">
      {['Ada', 'Ben', 'Cara', 'Dan', 'Eva'].map((name) => (
        <Avatar key={name} alt={name}>
          {name.slice(0, 1)}
        </Avatar>
      ))}
    </AvatarGroup>
  );
}
```

展开代码

### 形状

通过 `Avatar.shape` 设置圆形或方形头像。


圆形

LF

方形

LF

shapes.tsx

复制代码

```tsx lineNumbers file="../../src/examples/avatar/shapes.tsx"
import { Avatar, Flex, Grid, Text } from '@ifhover/leaf-ui';

export function AvatarShapes() {
  return (
    <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
      <Text tone="muted">圆形</Text>
      <Flex align="center" wrap>
        <Avatar shape="circle" alt="Leaf">
          LF
        </Avatar>
      </Flex>
      <Text tone="muted">方形</Text>
      <Flex align="center" wrap>
        <Avatar shape="square" alt="Leaf">
          LF
        </Avatar>
      </Flex>
    </Grid>
  );
}
```

展开代码


## API

### AvatarGroup API

成组展示成员头像及折叠人数的参数。

#### AvatarGroupProps API

| 属性           | 类型                                      | 默认值        | 说明                   |
| ------------ | --------------------------------------- | ---------- | -------------------- |
| `maxCount`   | `number`                                | `Infinity` | 最多展示的头像数，超出部分折叠为 +N。 |
| `size`       | [`AvatarProps`](#avatar-api)`['size']`  | —          | 头像尺寸预设；数字为像素值。       |
| `shape`      | [`AvatarProps`](#avatar-api)`['shape']` | —          | 裁剪形状                 |
| `maxContent` | `(hiddenCount: number) => ReactNode`    | —          | 自定义溢出人数              |

### Avatar API

组内单个成员头像的参数。

| 属性           | 类型                                                                                   | 默认值        | 说明                                              |
| ------------ | ------------------------------------------------------------------------------------ | ---------- | ----------------------------------------------- |
| `src`        | `string`                                                                             | —          | 头像图片地址。                                         |
| `srcSet`     | `string`                                                                             | —          | 响应式图片候选。                                        |
| `imageProps` | `Omit<ImgHTMLAttributes<HTMLImageElement>, 'src' \| 'srcSet' \| 'alt' \| 'onError'>` | —          | 图片原生属性，如 loading、sizes、crossOrigin、objectFit 样式 |
| `alt`        | `string`                                                                             | 文字或语言默认值   | 可访问名称                                           |
| `size`       | `'sm' \| 'md' \| 'lg' \| number`                                                     | `'md'`     | 预设尺寸或像素值                                        |
| `shape`      | `'circle' \| 'square'`                                                               | `'circle'` | 形状                                              |
| `icon`       | `ReactNode`                                                                          | —          | 没有图片时显示的图标。                                     |
| `onError`    | `() => void`                                                                         | —          | 图片加载失败回调                                        |
| `children`   | `ReactNode`                                                                          | —          | 没有图片时显示的文字或内容。                                  |
