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, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/components/avatar.md.

AvatarGroup 头像组

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

基础用法

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

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 统一设置组内头像尺寸。

小
中
大
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 为头像提供成员名称;只显示首字母时,也应提供完整名称。

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 或默认图标。更换图片地址后会重试加载。

文字回退
默认图标
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 查看其余成员。

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 设置圆形或方形头像。

圆形
方形
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

属性类型默认值说明
maxCountnumberInfinity最多展示的头像数,超出部分折叠为 +N。
sizeAvatarProps['size']—头像尺寸预设;数字为像素值。
shapeAvatarProps['shape']—裁剪形状
maxContent(hiddenCount: number) => ReactNode—自定义溢出人数

Avatar API

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

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