基础组件

头像

用户头像，优先显示图片，图片加载失败时显示文字 fallback，支持自定义尺寸。

安装

bash

npx polyui add avatar

尺寸

HRHRHRHR

tsx

import { Avatar, AvatarImage, AvatarFallback } from "@polyui/react/avatar"
export function AvatarSizes() {
  return (
    <div className="flex flex-wrap items-center gap-4">
      {/* --- 变体1: 小尺寸 --- */}
      <Avatar size="sm">
        <AvatarImage src="https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-5.png" alt="Hallie Richards" />
        <AvatarFallback className="text-xs">HR</AvatarFallback>
      </Avatar>

      {/* --- 变体2: 默认尺寸 --- */}
      <Avatar>
        <AvatarImage src="https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-5.png" alt="Hallie Richards" />
        <AvatarFallback className="text-xs">HR</AvatarFallback>
      </Avatar>

      {/* --- 变体3: 大尺寸 --- */}
      <Avatar size="lg">
        <AvatarImage src="https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-5.png" alt="Hallie Richards" />
        <AvatarFallback className="text-xs">HR</AvatarFallback>
      </Avatar>

      {/* --- 变体4: 自定义超大尺寸 --- */}
      <Avatar className="size-12">
        <AvatarImage src="https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-5.png" alt="Hallie Richards" />
        <AvatarFallback>HR</AvatarFallback>
      </Avatar>
    </div>
  )
}

形状样式

HRHRHR

tsx

import { Avatar, AvatarImage, AvatarFallback } from "@polyui/react/avatar"
import { HomeIcon } from "lucide-react"
export function AvatarShapeStyle() {
  return (
    <div className="flex flex-wrap items-center gap-4">
      {/* --- 变体5: 方形 --- */}
      <Avatar className="rounded-sm after:rounded-sm">
        <AvatarImage
          src="https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-5.png"
          alt="Hallie Richards"
          className="rounded-sm"
        />
        <AvatarFallback className="rounded-sm text-xs">HR</AvatarFallback>
      </Avatar>

      {/* --- 变体6: 带 ring --- */}
      <Avatar className="ring-ring ring-2">
        <AvatarImage src="https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-5.png" alt="Hallie Richards" />
        <AvatarFallback className="text-xs">HR</AvatarFallback>
      </Avatar>

      {/* --- 变体7: Fallback 纯文字 --- */}
      <Avatar>
        <AvatarFallback className="text-xs">HR</AvatarFallback>
      </Avatar>

      {/* --- 变体8: Fallback 图标 --- */}
      <Avatar>
        <AvatarFallback className="bg-indigo-500/10 text-indigo-500">
          <HomeIcon className="size-4" />
        </AvatarFallback>
      </Avatar>
    </div>
  )
}

状态

tsx

import { Avatar, AvatarImage, AvatarFallback } from "@polyui/react/avatar"
import { BadgeCheckIcon, CheckIcon } from "lucide-react"
export function AvatarStatus() {
  return (
    <div className="flex flex-wrap items-center gap-6">
      {/* --- 变体9: 在线（绿色圆点） --- */}
      <div className="relative w-fit">
        <Avatar>
          <AvatarImage src="https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-5.png" alt="Hallie Richards" />
          <AvatarFallback className="text-xs">HR</AvatarFallback>
        </Avatar>
        <span className="border-background bg-green-500 absolute -right-0.5 -bottom-0.5 size-3 rounded-full border-2">
          <span className="sr-only">Online</span>
        </span>
      </div>

      {/* --- 变体10: 忙碌（红色圆点） --- */}
      <div className="relative w-fit">
        <Avatar>
          <AvatarImage src="https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-5.png" alt="Hallie Richards" />
          <AvatarFallback className="text-xs">HR</AvatarFallback>
        </Avatar>
        <span className="border-background bg-destructive absolute -right-0.5 -bottom-0.5 size-3 rounded-full border-2">
          <span className="sr-only">Busy</span>
        </span>
      </div>

      {/* --- 变体11: 离开（amber 圆点，方形头像） --- */}
      <div className="relative w-fit">
        <Avatar className="rounded-sm after:rounded-sm">
          <AvatarImage
            src="https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-5.png"
            alt="Hallie Richards"
            className="rounded-sm"
          />
          <AvatarFallback className="rounded-sm text-xs">HR</AvatarFallback>
        </Avatar>
        <span className="border-background absolute -top-1.5 -right-1.5 size-3 rounded-full border-2 bg-amber-600 dark:bg-amber-400">
          <span className="sr-only">Away</span>
        </span>
      </div>

      {/* --- 变体12: 已认证（ring + check 图标） --- */}
      <div className="relative w-fit">
        <Avatar className="size-10 ring-offset-background ring-2 ring-green-600 ring-offset-2 dark:ring-green-400">
          <AvatarImage src="https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-5.png" alt="Hallie Richards" />
          <AvatarFallback className="text-xs">HR</AvatarFallback>
        </Avatar>
        <span className="absolute -right-1.5 -bottom-1.5 inline-flex size-4 items-center justify-center rounded-full bg-green-600 dark:bg-green-400">
          <CheckIcon className="size-3 text-white" />
        </span>
      </div>

      {/* --- 变体13: 蓝色认证徽章 --- */}
      <div className="relative w-fit">
        <Avatar className="size-10">
          <AvatarImage src="https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-5.png" alt="Hallie Richards" />
          <AvatarFallback className="text-xs">HR</AvatarFallback>
        </Avatar>
        <span className="absolute -top-1.5 -right-1.5">
          <span className="sr-only">Verified</span>
          <BadgeCheckIcon className="text-background size-5 fill-sky-500" />
        </span>
      </div>
    </div>
  )
}

操作与徽章

HR8

tsx

import { Avatar, AvatarImage, AvatarFallback } from "@polyui/react/avatar"
import { Badge } from "@polyui/react/badge"
import { PlusCircleIcon } from "lucide-react"
export function AvatarActionsBadges() {
  return (
    <div className="flex flex-wrap items-center gap-6">
      {/* --- 变体14: 添加按钮 --- */}
      <div className="relative w-fit">
        <Avatar className="size-10">
          <AvatarImage src="https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-5.png" alt="Hallie Richards" />
          <AvatarFallback className="text-xs">HR</AvatarFallback>
        </Avatar>
        <button className="focus-visible:ring-ring/50 absolute -right-1 -bottom-1 inline-flex cursor-pointer items-center justify-center rounded-full focus-visible:ring-[3px] focus-visible:outline-none">
          <PlusCircleIcon className="text-background size-5 fill-slate-400" />
          <span className="sr-only">Add</span>
        </button>
      </div>

      {/* --- 变体15: 数字通知角标 --- */}
      <div className="relative w-fit">
        <Avatar className="size-10 rounded-sm after:rounded-sm">
          <AvatarImage
            src="https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-5.png"
            alt="Hallie Richards"
            className="rounded-sm"
          />
          <AvatarFallback className="rounded-sm text-xs">HR</AvatarFallback>
        </Avatar>
        <Badge className="absolute -top-2.5 -right-2.5 h-5 min-w-5 bg-indigo-500 px-1 tabular-nums">8</Badge>
      </div>
    </div>
  )
}

分组

OSHLHRJW

OSHLHR

OSHLHRJW

Loved by 10K+ developers.

tsx

import { Avatar, AvatarImage, AvatarFallback, AvatarGroup, AvatarGroupCount } from "@polyui/react/avatar"
import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger } from "@polyui/react/dropdown-menu"
import { Tooltip, TooltipContent, TooltipTrigger, TooltipProvider } from "@polyui/react/tooltip"
import { PlusIcon } from "lucide-react"
export function AvatarGroups() {
  return (
    <div className="flex flex-col gap-4">
      {/* --- 变体16: AvatarGroup 组件（PolyUI 内置） --- */}
      <AvatarGroup>
        <Avatar>
          <AvatarImage src="https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-3.png" alt="Olivia Sparks" />
          <AvatarFallback className="text-xs">OS</AvatarFallback>
        </Avatar>
        <Avatar>
          <AvatarImage src="https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-6.png" alt="Howard Lloyd" />
          <AvatarFallback className="text-xs">HL</AvatarFallback>
        </Avatar>
        <Avatar>
          <AvatarImage src="https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-5.png" alt="Hallie Richards" />
          <AvatarFallback className="text-xs">HR</AvatarFallback>
        </Avatar>
        <Avatar>
          <AvatarImage src="https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-16.png" alt="Jenny Wilson" />
          <AvatarFallback className="text-xs">JW</AvatarFallback>
        </Avatar>
        <AvatarGroupCount>+9</AvatarGroupCount>
      </AvatarGroup>

      {/* --- 变体17: 大尺寸头像组 --- */}
      <div className="flex -space-x-3">
        {[
          { src: "https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-3.png", fallback: "OS", name: "Olivia Sparks" },
          { src: "https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-6.png", fallback: "HL", name: "Howard Lloyd" },
          {
            src: "https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-5.png",
            fallback: "HR",
            name: "Hallie Richards",
          },
          { src: "https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-16.png", fallback: "JW", name: "Jenny Wilson" },
        ].map((avatar) => (
          <Avatar key={avatar.name} className="ring-background size-12 ring-2">
            <AvatarImage src={avatar.src} alt={avatar.name} />
            <AvatarFallback>{avatar.fallback}</AvatarFallback>
          </Avatar>
        ))}
      </div>

      {/* --- 变体18: 头像组 + Tooltip（hover 展开） --- */}
      <TooltipProvider>
        <div className="flex -space-x-2 hover:space-x-1">
          {[
            {
              src: "https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-3.png",
              fallback: "OS",
              name: "Olivia Sparks",
            },
            { src: "https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-6.png", fallback: "HL", name: "Howard Lloyd" },
            {
              src: "https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-5.png",
              fallback: "HR",
              name: "Hallie Richards",
            },
            {
              src: "https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-16.png",
              fallback: "JW",
              name: "Jenny Wilson",
            },
          ].map((avatar) => (
            <Tooltip key={avatar.name}>
              <TooltipTrigger>
                <Avatar className="ring-background ring-2 transition-all duration-300 ease-in-out">
                  <AvatarImage src={avatar.src} alt={avatar.name} />
                  <AvatarFallback className="text-xs">{avatar.fallback}</AvatarFallback>
                </Avatar>
              </TooltipTrigger>
              <TooltipContent>{avatar.name}</TooltipContent>
            </Tooltip>
          ))}
        </div>
      </TooltipProvider>

      {/* --- 变体19: 头像组 + Dropdown 添加更多 --- */}
      <div className="flex -space-x-2">
        {[
          { src: "https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-3.png", fallback: "OS", name: "Olivia Sparks" },
          { src: "https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-6.png", fallback: "HL", name: "Howard Lloyd" },
          {
            src: "https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-5.png",
            fallback: "HR",
            name: "Hallie Richards",
          },
        ].map((avatar) => (
          <Avatar key={avatar.name} className="ring-background ring-2">
            <AvatarImage src={avatar.src} alt={avatar.name} />
            <AvatarFallback className="text-xs">{avatar.fallback}</AvatarFallback>
          </Avatar>
        ))}
        <DropdownMenu>
          <DropdownMenuTrigger
            render={
              <button className="bg-muted ring-background flex size-8 shrink-0 cursor-pointer items-center justify-center rounded-full ring-2" />
            }
          >
            <PlusIcon className="size-4" />
            <span className="sr-only">Add</span>
          </DropdownMenuTrigger>
          <DropdownMenuContent>
            {[
              {
                src: "https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-16.png",
                fallback: "JW",
                name: "Jenny Wilson",
              },
              {
                src: "https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-1.png",
                fallback: "DR",
                name: "Darlene Robertson",
              },
              {
                src: "https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-2.png",
                fallback: "LA",
                name: "Leslie Alexander",
              },
            ].map((avatar) => (
              <DropdownMenuItem key={avatar.name}>
                <Avatar>
                  <AvatarImage src={avatar.src} alt={avatar.name} />
                  <AvatarFallback className="text-xs">{avatar.fallback}</AvatarFallback>
                </Avatar>
                <span>{avatar.name}</span>
              </DropdownMenuItem>
            ))}
          </DropdownMenuContent>
        </DropdownMenu>
      </div>

      {/* --- 变体20: 头像组 + 圆形容器 + 计数 --- */}
      <div className="bg-background flex items-center rounded-full border p-1 shadow-sm">
        <div className="flex -space-x-2">
          {[
            {
              src: "https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-3.png",
              fallback: "OS",
              name: "Olivia Sparks",
            },
            { src: "https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-6.png", fallback: "HL", name: "Howard Lloyd" },
            {
              src: "https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-5.png",
              fallback: "HR",
              name: "Hallie Richards",
            },
            {
              src: "https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-16.png",
              fallback: "JW",
              name: "Jenny Wilson",
            },
          ].map((avatar) => (
            <Avatar key={avatar.name} className="ring-background ring-2">
              <AvatarImage src={avatar.src} alt={avatar.name} />
              <AvatarFallback className="text-xs">{avatar.fallback}</AvatarFallback>
            </Avatar>
          ))}
        </div>
        <span className="text-muted-foreground flex items-center justify-center rounded-full bg-transparent px-2 text-xs shadow-none">
          +3
        </span>
      </div>

      {/* --- 变体21: 人气指示器 --- */}
      <div className="bg-background flex flex-wrap items-center justify-center rounded-full border p-1 shadow-sm">
        <div className="flex -space-x-1">
          {[
            {
              src: "https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-3.png",
              fallback: "OS",
              name: "Olivia Sparks",
            },
            { src: "https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-6.png", fallback: "HL", name: "Howard Lloyd" },
            {
              src: "https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-5.png",
              fallback: "HR",
              name: "Hallie Richards",
            },
            {
              src: "https://cdn.shadcnstudio.com/ss-assets/avatar/avatar-16.png",
              fallback: "JW",
              name: "Jenny Wilson",
            },
          ].map((avatar) => (
            <Avatar key={avatar.name} className="ring-background size-6 ring-2">
              <AvatarImage src={avatar.src} alt={avatar.name} />
              <AvatarFallback className="text-xs">{avatar.fallback}</AvatarFallback>
            </Avatar>
          ))}
        </div>
        <p className="text-muted-foreground px-2 text-xs">
          Loved by <strong className="text-foreground font-medium">10K+</strong> developers.
        </p>
      </div>
    </div>
  )
}

属性

Avatar

属性	类型	默认值	说明
`className`	`string`	`—`	自定义样式类名，可用于控制尺寸

AvatarImage

属性	类型	默认值	说明
`src`	`string`	`—`	头像图片的 URL，为空或加载失败时显示 AvatarFallback
`alt`	`string`	`—`	图片的 alt 文本，用于无障碍访问

AvatarFallback

属性	类型	默认值	说明
`delayMs`	`number`	`300`	显示 fallback 前等待的毫秒数，避免图片快速加载时闪烁