Avatar 头像
展示用户头像图片，并提供可定制的回退内容。
引入
import { Avatar } from '@heroui/react';用法
JDBJR
import {Avatar} from "@heroui/react";
export function Basic() {
return (
<div className="flex items-center gap-4">组件结构
引入 Avatar 组件，并通过点语法访问各部分。
import { Avatar } from '@heroui/react';
export default () => (
<Avatar>
<Avatar.Image/>
<Avatar.Fallback/>
</Avatar>
)尺寸
SMMDLG
import {Avatar} from "@heroui/react";
export function Sizes() {
return (
<div className="flex items-center gap-4">颜色
DFACSCWRDG
import {Avatar} from "@heroui/react";
export function Colors() {
return (
<div className="flex items-center gap-4">变体
强调
默认
成功
警告
危险
字母
AG
AG
AG
AG
AG
柔和字母
AG
AG
AG
AG
AG
图标
柔和图标
图片
强
默
成
警
危
import {Person} from "@gravity-ui/icons";
import {Avatar, Separator} from "@heroui/react";
const colors = ["accent", "default", "success", "warning", "danger"] as const;
回退内容
JDGB
import {Person} from "@gravity-ui/icons";
import {Avatar} from "@heroui/react";
export function Fallback() {
return (头像组
张明李华王芳刘洋
张明李华王芳+2
import {Avatar} from "@heroui/react";
const users = [
{
id: 1,自定义样式
XLSQ
GB
ON
import {Avatar} from "@heroui/react";
export function CustomStyles() {
return (
<div className="flex items-center gap-4">样式
传入 Tailwind CSS 类
import { Avatar } from '@heroui/react';
function CustomAvatar() {
return (
<Avatar className="size-20">
<Avatar.Image src="..." alt="..." />
<Avatar.Fallback>XL</Avatar.Fallback>
</Avatar>
);
}自定义组件类
若要自定义 Avatar 组件类，可以使用 @layer components 指令。
了解更多。
@layer components {
.avatar {
@apply size-16 border-2 border-primary;
}
.avatar__fallback {
@apply bg-gradient-to-br from-purple-500 to-pink-500;
}
}HeroUI 遵循 BEM 方法论，确保组件变体与状态可复用且易于自定义。
CSS 类
Avatar 组件使用以下 CSS 类（查看源码样式）：
基础类
.avatar- 基础容器，默认尺寸（size-10）.avatar__image- 图片元素，方形比例.avatar__fallback- 回退容器，内容居中
尺寸修饰
.avatar--sm- 小尺寸（size-8）.avatar--md- 中尺寸（默认，无额外样式）.avatar--lg- 大尺寸（size-12）
变体修饰
.avatar--soft- Soft 变体，背景更浅
颜色修饰
.avatar__fallback--default- 默认文字颜色.avatar__fallback--accent- 强调文字颜色.avatar__fallback--success- 成功文字颜色.avatar__fallback--warning- 警告文字颜色.avatar__fallback--danger- 危险文字颜色
API 参考
Avatar Props
| Prop | 类型 | 默认值 | 描述 |
|---|---|---|---|
size | 'sm' | 'md' | 'lg' | 'md' | Avatar 尺寸 |
color | 'default' | 'accent' | 'success' | 'warning' | 'danger' | 'default' | 回退区域的颜色主题 |
variant | 'default' | 'soft' | 'default' | 视觉样式变体 |
className | string | - | 额外的 CSS 类 |
Avatar.Image Props
| Prop | 类型 | 默认值 | 描述 |
|---|---|---|---|
src | string | - | 图片地址 |
srcSet | string | - | 响应式图片的 srcset |
sizes | string | - | 响应式图片的 sizes |
alt | string | - | 图片替代文本 |
onLoad | (event: SyntheticEvent<HTMLImageElement>) => void | - | 图片加载成功时的事件处理函数 |
onError | (event: SyntheticEvent<HTMLImageElement>) => void | - | 图片加载失败时的事件处理函数 |
crossOrigin | 'anonymous' | 'use-credentials' | - | 图片请求的 CORS 设置 |
loading | 'eager' | 'lazy' | - | 原生懒加载属性 |
className | string | - | 额外的 CSS 类 |
Avatar.Fallback Props
| Prop | 类型 | 默认值 | 描述 |
|---|---|---|---|
delayMs | number | - | 显示回退内容前的延迟（减轻闪烁） |
color | 'default' | 'accent' | 'success' | 'warning' | 'danger' | - | 覆盖父级的颜色 |
className | string | - | 额外的 CSS 类 |
