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

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

# Avatar 头像

展示用户、团队或对象的头像。

## 尺寸与形状


小尺寸LF

默认尺寸LE

大尺寸 · 方形UI

未读提醒A

basic.tsx

复制代码

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

export function AvatarBasic() {
  return (
    <Flex gap="md" align="center" wrap justify="center">
      <Flex direction="column" gap="sm" align="start">
        <Text>小尺寸</Text>
        <Avatar size="sm">LF</Avatar>
      </Flex>
      <Flex direction="column" gap="sm" align="start">
        <Text>默认尺寸</Text>
        <Avatar>LE</Avatar>
      </Flex>
      <Flex direction="column" gap="sm" align="start">
        <Text>大尺寸 · 方形</Text>
        <Avatar size="lg" shape="square">
          UI
        </Avatar>
      </Flex>
      <Flex direction="column" gap="sm" align="start">
        <Text>未读提醒</Text>
        <Badge dot>
          <Avatar alt="未读消息">A</Avatar>
        </Badge>
      </Flex>
    </Flex>
  );
}
```

展开代码

## 图片头像


圆形图片![](../avatar-portrait.svg)

方形图片![](../avatar-portrait.svg)

image.tsx

复制代码

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

export function AvatarImage() {
  const image = '../avatar-portrait.svg';
  return (
    <Flex gap="md" align="center" wrap justify="center">
      <Flex direction="column" gap="sm" align="start">
        <Text>圆形图片</Text>
        <Avatar src={image} alt="Alex" size="lg" />
      </Flex>
      <Flex direction="column" gap="sm" align="start">
        <Text>方形图片</Text>
        <Avatar src={image} alt="Alex" size={64} shape="square" imageProps={{ loading: 'lazy' }} />
      </Flex>
    </Flex>
  );
}
```

展开代码

## 加载失败与默认头像


加载失败时显示文字LF![](data:image/png;base64,broken)

未设置图片时显示默认图标

fallback.tsx

复制代码

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

export function AvatarFallback() {
  return (
    <Flex gap="md" align="center" wrap justify="center">
      <Flex direction="column" gap="sm" align="start">
        <Text>加载失败时显示文字</Text>
        <Avatar src="data:image/png;base64,broken" alt="图片加载失败">
          LF
        </Avatar>
      </Flex>
      <Flex direction="column" gap="sm" align="start">
        <Text>未设置图片时显示默认图标</Text>
        <Avatar alt="访客" />
      </Flex>
    </Flex>
  );
}
```

展开代码

## 扩展用法


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}>
      {['Ada', 'Ben', 'Cara', 'Dan', 'Eva'].map((name) => (
        <Avatar key={name} alt={name}>
          {name.slice(0, 1)}
        </Avatar>
      ))}
    </AvatarGroup>
  );
}
```

展开代码

## Avatar API

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

## 类型

可导入以下类型定义属性、组装数据或处理回调。

```ts
import type { AvatarProps } from '@ifhover/leaf-ui';
```

## 使用说明

图片加载失败时自动显示 `children`、`icon` 或默认头像，图片地址变化后会重试。`alt` 为头像提供可访问名称；图片自身避免重复朗读。`imageProps.style` 可调整裁切方式。

## 扩展类型

```ts
import type { AvatarGroupProps } from '@ifhover/leaf-ui';
```

## AvatarGroupProps API

| 属性           | 类型                                   | 默认值        | 说明        |
| ------------ | ------------------------------------ | ---------- | --------- |
| `maxCount`   | `number`                             | `Infinity` | 最多勾选或展示数量 |
| `size`       | `'sm' \| 'md' \| 'lg' \| number`     | —          | 尺寸或间距预设   |
| `shape`      | `'circle' \| 'square'`               | —          | 裁剪形状      |
| `maxContent` | `(hiddenCount: number) => ReactNode` | —          | 自定义溢出人数   |