Avatar

图片头像

文本头像

张

李

图标头像

不同尺寸

"use client";

import { Avatar } from "@/components/composed/avatar/avatar";
import { User, Mail, Heart, Star } from "lucide-react";

export function AvatarDemo() {
  return (
    <div className="space-y-6">
      <div>
        <h3 className="mb-3 text-sm font-medium">图片头像</h3>
        <div className="flex items-center gap-4">
          <Avatar
            src="https://api.dicebear.com/7.x/avataaars/svg?seed=Felix"
            alt="User 1"
          />
          <Avatar
            src="https://api.dicebear.com/7.x/avataaars/svg?seed=Aneka"
            alt="User 2"
          />
          <Avatar
            src="https://api.dicebear.com/7.x/avataaars/svg?seed=John"
            alt="User 3"
          />
        </div>
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">文本头像</h3>
        <div className="flex items-center gap-4">
          <Avatar style={{ backgroundColor: "#fde3cf" }}>A</Avatar>
          <Avatar style={{ backgroundColor: "#f56a00" }}>K</Avatar>
          <Avatar style={{ backgroundColor: "#87d068" }}>张</Avatar>
          <Avatar style={{ backgroundColor: "#1677ff" }}>李</Avatar>
        </div>
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">图标头像</h3>
        <div className="flex items-center gap-4">
          <Avatar
            style={{ backgroundColor: "#87d068" }}
            icon={<User className="h-4 w-4" />}
          />
          <Avatar
            style={{ backgroundColor: "#1677ff" }}
            icon={<Mail className="h-4 w-4" />}
          />
          <Avatar
            style={{ backgroundColor: "#f56a00" }}
            icon={<Heart className="h-4 w-4" />}
          />
          <Avatar
            style={{ backgroundColor: "#fde3cf" }}
            icon={<Star className="h-4 w-4" />}
          />
        </div>
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">不同尺寸</h3>
        <div className="flex items-center gap-4">
          <Avatar size="sm" style={{ backgroundColor: "#1677ff" }}>
            S
          </Avatar>
          <Avatar size="md" style={{ backgroundColor: "#1677ff" }}>
            M
          </Avatar>
          <Avatar size="lg" style={{ backgroundColor: "#1677ff" }}>
            L
          </Avatar>
        </div>
      </div>
    </div>
  );
}

Avatar 头像组件用于展示用户、团队或实体的视觉标识，支持图片、文本、图标等多种展示形式，适用于用户列表、评论区、聊天界面等场景。

概述

多种展示形式：支持图片、文本、图标三种展示方式
灵活的尺寸：提供 sm、md、lg 三种预设尺寸
自定义样式：支持自定义背景色、文字颜色等样式
头像组：支持多个头像的组合展示，带重叠效果
头像标题：支持展示名称和时间信息
类型安全：完整的 TypeScript 类型定义

快速开始

import { Avatar, AvatarGroup, AvatarHeader } from "@/registry/wuhan/composed/avatar/avatar";

export function Example() {
  return <Avatar src="https://example.com/avatar.jpg" />;
}

特性

图片头像：支持传入 src 属性显示图片
文本头像：支持传入文本作为 children 显示
图标头像：支持传入图标组件显示
优先级渲染：src > icon > children 的渲染优先级
图片加载失败：自动降级到文本或图标
头像组合：AvatarGroup 支持多个头像重叠显示
数量限制：AvatarGroup 支持 maxCount 限制显示数量
头像标题：AvatarHeader 支持展示名称和时间

安装

pnpm dlx shadcn@latest add http://localhost:3000/r/wuhan/avatar.json

代码演示

基础用法

演示图片头像、文本头像和自定义背景色。

"use client";

import { Avatar } from "@/components/composed/avatar/avatar";

export function AvatarDefault() {
  return (
    <div className="flex items-center gap-4">
      <Avatar
        src="https://api.dicebear.com/7.x/avataaars/svg?seed=Felix"
        alt="User"
      />
      <Avatar>A</Avatar>
      <Avatar style={{ backgroundColor: "#f56a00" }}>K</Avatar>
    </div>
  );
}

综合演示

展示图片、文本、图标和不同尺寸的头像。

图片头像

文本头像

张

李

图标头像

不同尺寸

"use client";

import { Avatar } from "@/components/composed/avatar/avatar";
import { User, Mail, Heart, Star } from "lucide-react";

export function AvatarDemo() {
  return (
    <div className="space-y-6">
      <div>
        <h3 className="mb-3 text-sm font-medium">图片头像</h3>
        <div className="flex items-center gap-4">
          <Avatar
            src="https://api.dicebear.com/7.x/avataaars/svg?seed=Felix"
            alt="User 1"
          />
          <Avatar
            src="https://api.dicebear.com/7.x/avataaars/svg?seed=Aneka"
            alt="User 2"
          />
          <Avatar
            src="https://api.dicebear.com/7.x/avataaars/svg?seed=John"
            alt="User 3"
          />
        </div>
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">文本头像</h3>
        <div className="flex items-center gap-4">
          <Avatar style={{ backgroundColor: "#fde3cf" }}>A</Avatar>
          <Avatar style={{ backgroundColor: "#f56a00" }}>K</Avatar>
          <Avatar style={{ backgroundColor: "#87d068" }}>张</Avatar>
          <Avatar style={{ backgroundColor: "#1677ff" }}>李</Avatar>
        </div>
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">图标头像</h3>
        <div className="flex items-center gap-4">
          <Avatar
            style={{ backgroundColor: "#87d068" }}
            icon={<User className="h-4 w-4" />}
          />
          <Avatar
            style={{ backgroundColor: "#1677ff" }}
            icon={<Mail className="h-4 w-4" />}
          />
          <Avatar
            style={{ backgroundColor: "#f56a00" }}
            icon={<Heart className="h-4 w-4" />}
          />
          <Avatar
            style={{ backgroundColor: "#fde3cf" }}
            icon={<Star className="h-4 w-4" />}
          />
        </div>
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">不同尺寸</h3>
        <div className="flex items-center gap-4">
          <Avatar size="sm" style={{ backgroundColor: "#1677ff" }}>
            S
          </Avatar>
          <Avatar size="md" style={{ backgroundColor: "#1677ff" }}>
            M
          </Avatar>
          <Avatar size="lg" style={{ backgroundColor: "#1677ff" }}>
            L
          </Avatar>
        </div>
      </div>
    </div>
  );
}

文本头像

使用文本作为头像内容，支持自定义背景色和文字颜色。

张三

李四

王

"use client";

import { Avatar } from "@/components/composed/avatar/avatar";

export function AvatarText() {
  return (
    <div className="flex items-center gap-4">
      <Avatar style={{ backgroundColor: "#fde3cf", color: "#f56a00" }}>
        A
      </Avatar>
      <Avatar style={{ backgroundColor: "#f56a00", color: "#fff" }}>K</Avatar>
      <Avatar style={{ backgroundColor: "#87d068", color: "#fff" }}>
        张三
      </Avatar>
      <Avatar style={{ backgroundColor: "#1677ff", color: "#fff" }}>
        李四
      </Avatar>
      <Avatar style={{ backgroundColor: "#eb2f96", color: "#fff" }}>王</Avatar>
    </div>
  );
}

图标头像

使用图标作为头像内容。

"use client";

import { Avatar } from "@/components/composed/avatar/avatar";
import { User, Mail, Heart, Star, Camera, Music } from "lucide-react";

export function AvatarIcon() {
  return (
    <div className="flex items-center gap-4">
      <Avatar
        style={{ backgroundColor: "#87d068" }}
        icon={<User className="h-4 w-4" />}
      />
      <Avatar
        style={{ backgroundColor: "#1677ff" }}
        icon={<Mail className="h-4 w-4" />}
      />
      <Avatar
        style={{ backgroundColor: "#f56a00" }}
        icon={<Heart className="h-4 w-4" />}
      />
      <Avatar
        style={{ backgroundColor: "#eb2f96" }}
        icon={<Star className="h-4 w-4" />}
      />
      <Avatar
        style={{ backgroundColor: "#52c41a" }}
        icon={<Camera className="h-4 w-4" />}
      />
      <Avatar
        style={{ backgroundColor: "#faad14" }}
        icon={<Music className="h-4 w-4" />}
      />
    </div>
  );
}

不同尺寸

提供 sm、md、lg 三种尺寸。

小尺寸 (sm)

中尺寸 (md) - 默认

大尺寸 (lg)

"use client";

import { Avatar } from "@/components/composed/avatar/avatar";

export function AvatarSizes() {
  return (
    <div className="space-y-6">
      <div>
        <h3 className="mb-3 text-sm font-medium">小尺寸 (sm)</h3>
        <div className="flex items-center gap-4">
          <Avatar
            size="sm"
            src="https://api.dicebear.com/7.x/avataaars/svg?seed=Felix"
          />
          <Avatar size="sm" style={{ backgroundColor: "#1677ff" }}>
            A
          </Avatar>
        </div>
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">中尺寸 (md) - 默认</h3>
        <div className="flex items-center gap-4">
          <Avatar
            size="md"
            src="https://api.dicebear.com/7.x/avataaars/svg?seed=Felix"
          />
          <Avatar size="md" style={{ backgroundColor: "#1677ff" }}>
            A
          </Avatar>
        </div>
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">大尺寸 (lg)</h3>
        <div className="flex items-center gap-4">
          <Avatar
            size="lg"
            src="https://api.dicebear.com/7.x/avataaars/svg?seed=Felix"
          />
          <Avatar size="lg" style={{ backgroundColor: "#1677ff" }}>
            A
          </Avatar>
        </div>
      </div>
    </div>
  );
}

头像组

多个头像组合展示，支持重叠效果和数量限制。

基础头像组

限制显示数量

自定义间距

图片头像组

"use client";

import { Avatar, AvatarGroup } from "@/components/composed/avatar/avatar";
import { User, Mail } from "lucide-react";

export function AvatarGroupDemo() {
  return (
    <div className="space-y-6">
      <div>
        <h3 className="mb-3 text-sm font-medium">基础头像组</h3>
        <AvatarGroup>
          <Avatar style={{ backgroundColor: "#fde3cf" }}>A</Avatar>
          <Avatar style={{ backgroundColor: "#f56a00" }}>K</Avatar>
          <Avatar
            style={{ backgroundColor: "#87d068" }}
            icon={<User className="h-4 w-4" />}
          />
          <Avatar
            style={{ backgroundColor: "#1677ff" }}
            icon={<Mail className="h-4 w-4" />}
          />
        </AvatarGroup>
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">限制显示数量</h3>
        <AvatarGroup maxCount={3}>
          <Avatar style={{ backgroundColor: "#fde3cf" }}>A</Avatar>
          <Avatar style={{ backgroundColor: "#f56a00" }}>K</Avatar>
          <Avatar style={{ backgroundColor: "#87d068" }}>Z</Avatar>
          <Avatar style={{ backgroundColor: "#1677ff" }}>L</Avatar>
          <Avatar style={{ backgroundColor: "#eb2f96" }}>W</Avatar>
        </AvatarGroup>
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">自定义间距</h3>
        <AvatarGroup spacing={-12}>
          <Avatar style={{ backgroundColor: "#fde3cf" }}>A</Avatar>
          <Avatar style={{ backgroundColor: "#f56a00" }}>K</Avatar>
          <Avatar style={{ backgroundColor: "#87d068" }}>Z</Avatar>
          <Avatar style={{ backgroundColor: "#1677ff" }}>L</Avatar>
        </AvatarGroup>
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">图片头像组</h3>
        <AvatarGroup>
          <Avatar src="https://api.dicebear.com/7.x/avataaars/svg?seed=Felix" />
          <Avatar src="https://api.dicebear.com/7.x/avataaars/svg?seed=Aneka" />
          <Avatar src="https://api.dicebear.com/7.x/avataaars/svg?seed=John" />
        </AvatarGroup>
      </div>
    </div>
  );
}

带名称和时间

展示带有名称和时间信息的头像。

基础用法

张三2小时前

使用文本头像

李

李四刚刚

使用图标头像

王五5分钟前

自定义样式

赵

赵六昨天

不同尺寸

小头像1小时前

中等头像2小时前

大头像3小时前

"use client";

import { AvatarHeader } from "@/components/composed/avatar/avatar";
import { User } from "lucide-react";

export function AvatarHeaderDemo() {
  return (
    <div className="space-y-6">
      <div>
        <h3 className="mb-3 text-sm font-medium">基础用法</h3>
        <AvatarHeader
          avatar={{
            src: "https://api.dicebear.com/7.x/avataaars/svg?seed=Felix",
          }}
          name="张三"
          time="2小时前"
        />
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">使用文本头像</h3>
        <AvatarHeader
          avatar={{
            children: "李",
            style: { backgroundColor: "#1677ff", color: "white" },
          }}
          name="李四"
          time="刚刚"
        />
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">使用图标头像</h3>
        <AvatarHeader
          avatar={{
            icon: <User className="h-4 w-4" />,
            style: { backgroundColor: "#87d068" },
          }}
          name="王五"
          time="5分钟前"
        />
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">自定义样式</h3>
        <AvatarHeader
          avatar={{
            children: "赵",
            style: { backgroundColor: "#eb2f96", color: "white" },
          }}
          name="赵六"
          time="昨天"
          nameStyle={{ color: "#eb2f96", fontWeight: "bold" }}
          timeStyle={{ color: "#999" }}
        />
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">不同尺寸</h3>
        <div className="space-y-3">
          <AvatarHeader
            avatar={{
              src: "https://api.dicebear.com/7.x/avataaars/svg?seed=Felix",
              size: "sm",
            }}
            name="小头像"
            time="1小时前"
          />
          <AvatarHeader
            avatar={{
              src: "https://api.dicebear.com/7.x/avataaars/svg?seed=Aneka",
              size: "md",
            }}
            name="中等头像"
            time="2小时前"
          />
          <AvatarHeader
            avatar={{
              src: "https://api.dicebear.com/7.x/avataaars/svg?seed=John",
              size: "lg",
            }}
            name="大头像"
            time="3小时前"
          />
        </div>
      </div>
    </div>
  );
}

API

Avatar

头像组件的主要 API。

属性	类型	默认值	说明
`src`	`string`	-	图片地址
`alt`	`string`	`"avatar"`	图片替代文本
`children`	`ReactNode`	-	文本内容，当没有 src 或图片加载失败时显示
`icon`	`ReactNode`	-	图标内容
`size`	`"sm" \| "md" \| "lg"`	`"md"`	头像尺寸
`style`	`CSSProperties`	-	自定义样式（可用于设置背景色等）
`className`	`string`	-	自定义类名

AvatarGroup

头像组组件，用于展示多个头像。

属性	类型	默认值	说明
`children`	`ReactNode`	-	Avatar 组件列表
`maxCount`	`number`	-	最大显示数量，超出部分显示 +N
`spacing`	`number`	`-8`	头像间距（负值产生重叠效果）
`className`	`string`	-	自定义类名

AvatarHeader

带名称和时间的头像组件。

属性	类型	默认值	说明
`avatar`	`AvatarProps`	-	Avatar 组件的 props
`avatarRender`	`ReactNode`	-	自定义头像渲染内容
`name`	`ReactNode`	-	名称
`time`	`ReactNode`	-	时间信息
`nameStyle`	`CSSProperties`	-	名称样式
`timeStyle`	`CSSProperties`	-	时间样式
`className`	`string`	-	自定义类名

使用场景

1. 用户列表

<div className="space-y-3">
  <AvatarHeader
    avatar={{ src: "https://example.com/user1.jpg" }}
    name="张三"
    time="在线"
  />
  <AvatarHeader
    avatar={{ src: "https://example.com/user2.jpg" }}
    name="李四"
    time="2小时前"
  />
</div>

2. 评论区

<AvatarHeader
  avatar={{ 
    children: "王",
    style: { backgroundColor: '#1677ff', color: 'white' }
  }}
  name="王五"
  time="刚刚"
/>

3. 团队成员

<AvatarGroup maxCount={5}>
  <Avatar src="https://example.com/member1.jpg" />
  <Avatar src="https://example.com/member2.jpg" />
  <Avatar src="https://example.com/member3.jpg" />
  {/* 更多成员... */}
</AvatarGroup>

4. 聊天列表

<AvatarHeader
  avatar={{ 
    icon: <User className="h-4 w-4" />,
    style: { backgroundColor: '#87d068' }
  }}
  name="客服小智"
  time="5分钟前"
/>

设计指南

尺寸选择

sm (24px)：适用于紧凑的列表、标签等场景
md (32px)：默认尺寸，适用于大多数场景
lg (40px)：适用于强调用户信息的场景

内容优先级

Avatar 组件按以下优先级渲染内容：

图片 (src)：优先显示图片
图标 (icon)：当没有图片或图片加载失败时显示图标
文本 (children)：当没有图片和图标时显示文本

颜色使用

使用 style 属性自定义背景色
文本头像建议使用品牌色或区分性强的颜色
确保文字与背景色有足够的对比度

头像组使用

默认间距 -8px 产生适度的重叠效果
使用 maxCount 避免显示过多头像
超出数量用 +N 标识

可访问性

图片头像默认提供 alt="avatar" 属性
支持自定义 alt 属性提升可访问性
文本头像使用语义化的 HTML 结构
支持键盘导航和屏幕阅读器

常见问题

1. 如何处理图片加载失败？

Avatar 组件会自动处理图片加载失败的情况。如果提供了 icon 或 children，会自动降级显示。

<Avatar 
  src="invalid-url.jpg"
  icon={<User />}
>
  A
</Avatar>

2. 如何自定义文本头像的样式？

使用 style 属性自定义背景色和文字颜色：

<Avatar style={{ backgroundColor: '#1677ff', color: 'white' }}>
  张
</Avatar>

3. AvatarGroup 如何控制重叠程度？

使用 spacing 属性控制头像间距，负值产生重叠效果：

<AvatarGroup spacing={-12}>
  {/* 重叠更多 */}
</AvatarGroup>

<AvatarGroup spacing={-4}>
  {/* 重叠较少 */}
</AvatarGroup>

4. AvatarHeader 如何自定义头像？

可以使用 avatar 属性传递 Avatar 的 props，或使用 avatarRender 完全自定义：

{/* 方式1: 传递 props */}
<AvatarHeader
  avatar={{ 
    src: "...",
    size: "lg"
  }}
  name="张三"
/>

{/* 方式2: 完全自定义 */}
<AvatarHeader
  avatarRender={<CustomAvatar />}
  name="张三"
/>

原语组件

Avatar 组件基于以下原语组件构建：

AvatarPrimitive: 头像容器组件
AvatarImagePrimitive: 图片组件
AvatarTextPrimitive: 文本组件
AvatarIconPrimitive: 图标容器组件
AvatarGroupPrimitive: 头像组容器组件
AvatarHeaderPrimitive: 头像标题容器组件
AvatarNamePrimitive: 名称组件
AvatarTimePrimitive: 时间组件

如需更灵活的定制，可以直接使用这些原语组件。

Avatar

图片头像

文本头像

图标头像

不同尺寸

图片头像

文本头像

图标头像

不同尺寸

小尺寸 (sm)

中尺寸 (md) - 默认

大尺寸 (lg)

基础头像组

限制显示数量

自定义间距

图片头像组

基础用法

使用文本头像

使用图标头像

自定义样式

不同尺寸

On this page