Skip to content
Lenso UI

Avatar 头像

显示用户头像，支持自定义 fallback 内容

用法

import { Avatar } from '@lenso/ui';

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.import { Avatar } from "@lenso/ui";import * as stylex from "@stylexjs/stylex";import { s } from "../card/display.stylex";
export function Basic() {  return (    <div {...stylex.props(s.row4)}>      <Avatar>        <Avatar.Image alt="John Doe" src="https://img.heroui.chat/image/avatar?w=400&h=400&u=3" />        <Avatar.Fallback>JD</Avatar.Fallback>      </Avatar>      <Avatar>        <Avatar.Image          alt="Blue"          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"        />        <Avatar.Fallback>B</Avatar.Fallback>      </Avatar>      <Avatar>        <Avatar.Fallback>JR</Avatar.Fallback>      </Avatar>    </div>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

组件结构

import { Avatar } from '@lenso/ui';
export default () => (  <Avatar>    <Avatar.Image/>    <Avatar.Fallback/>  </Avatar>)

示例

尺寸

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.import { Avatar } from "@lenso/ui";import * as stylex from "@stylexjs/stylex";import { s } from "../card/display.stylex";
export function Sizes() {  return (    <div {...stylex.props(s.row4)}>      <Avatar size="sm">        <Avatar.Image          alt="Small Avatar"          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"        />        <Avatar.Fallback>SM</Avatar.Fallback>      </Avatar>      <Avatar size="md">        <Avatar.Image          alt="Medium Avatar"          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg"        />        <Avatar.Fallback>MD</Avatar.Fallback>      </Avatar>      <Avatar size="lg">        <Avatar.Image          alt="Large Avatar"          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg"        />        <Avatar.Fallback>LG</Avatar.Fallback>      </Avatar>    </div>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

颜色

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.import { Avatar } from "@lenso/ui";import * as stylex from "@stylexjs/stylex";import { s } from "../card/display.stylex";
export function Colors() {  return (    <div {...stylex.props(s.row4)}>      <Avatar color="default">        <Avatar.Fallback>DF</Avatar.Fallback>      </Avatar>      <Avatar color="accent">        <Avatar.Fallback>AC</Avatar.Fallback>      </Avatar>      <Avatar color="success">        <Avatar.Fallback>SC</Avatar.Fallback>      </Avatar>      <Avatar color="warning">        <Avatar.Fallback>WR</Avatar.Fallback>      </Avatar>      <Avatar color="danger">        <Avatar.Fallback>DG</Avatar.Fallback>      </Avatar>    </div>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

变体

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.import { Person } from "@gravity-ui/icons";import { Avatar, Separator } from "@lenso/ui";import * as stylex from "@stylexjs/stylex";import { s } from "../card/display.stylex";
export function Variants() {  const colors = ["accent", "default", "success", "warning", "danger"] as const;  const variants = [    { content: "AG", label: "letter", type: "letter" },    { content: "AG", label: "letter soft", type: "letter-soft" },    { content: <Person />, label: "icon", type: "icon" },    { content: <Person />, label: "icon soft", type: "icon-soft" },    {      content: [        "https://img.heroui.chat/image/avatar?w=400&h=400&u=3",        "https://img.heroui.chat/image/avatar?w=400&h=400&u=4",        "https://img.heroui.chat/image/avatar?w=400&h=400&u=5",        "https://img.heroui.chat/image/avatar?w=400&h=400&u=8",        "https://img.heroui.chat/image/avatar?w=400&h=400&u=16",      ],      label: "img",      type: "img",    },  ] as const;  return (    <div {...stylex.props(s.column4)}>      <div {...stylex.props(s.row3)}>        <div {...stylex.props(s.labelCell)} />        {colors.map((color) => (          <div key={color} {...stylex.props(s.avatarCell)}>            <span {...stylex.props(s.textXs, s.muted, s.capitalize)}>{color}</span>          </div>        ))}      </div>      <Separator />      {variants.map((variant) => (        <div key={variant.label} {...stylex.props(s.row3)}>          <div {...stylex.props(s.labelCell, s.textSm, s.muted)}>{variant.label}</div>          {colors.map((color, colorIndex) => (            <div key={color} {...stylex.props(s.avatarCell)}>              <Avatar color={color} variant={variant.type.includes("soft") ? "soft" : "default"}>                {variant.type === "img" ? (                  <>                    <Avatar.Image alt={`Avatar ${color}`} src={variant.content[colorIndex] ?? ""} />                    <Avatar.Fallback>{color.charAt(0).toUpperCase()}</Avatar.Fallback>                  </>                ) : (                  <Avatar.Fallback>{variant.content}</Avatar.Fallback>                )}              </Avatar>            </div>          ))}        </div>      ))}    </div>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

回退内容

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.import { Person } from "@gravity-ui/icons";import { Avatar } from "@lenso/ui";import * as stylex from "@stylexjs/stylex";import { s } from "../card/display.stylex";
export function Fallback() {  return (    <div {...stylex.props(s.row4)}>      <Avatar>        <Avatar.Fallback>JD</Avatar.Fallback>      </Avatar>      <Avatar>        <Avatar.Fallback>          <Person />        </Avatar.Fallback>      </Avatar>      <Avatar>        <Avatar.Image          alt="Delayed Avatar"          src="https://invalid-url-to-show-fallback.com/image.jpg"        />        <Avatar.Fallback delay={600}>NA</Avatar.Fallback>      </Avatar>      <Avatar>        <Avatar.Fallback xstyle={s.gradientFallback}>GB</Avatar.Fallback>      </Avatar>    </div>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

自定义样式

自定义图片组件

在 Avatar.Image 上使用 asChild，即可与自定义图片组件组合。以下示例使用 Next.js Image 以实现优化加载。请将 src 传给 Avatar.Image，以便跟踪加载状态，并在图片就绪前显示回退内容。

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.import { Avatar } from "@lenso/ui";import Image from "next/image";
const SRC = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg";
export function CustomImageComponent() {  return (    <Avatar>      <Avatar.Image        alt="John Doe"        height={40}        src={SRC}        width={40}        render={<Image alt="John Doe" src={SRC} height={40} width={40} unoptimized />}      />      <Avatar.Fallback>JD</Avatar.Fallback>    </Avatar>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Tailwind CSS

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.import { Avatar } from "@lenso/ui";import { s } from "../card/display.stylex";
export function CustomStyles() {  return (    <Avatar xstyle={s.roundLg}>      <Avatar.Image alt="John Doe" src="https://img.heroui.chat/image/avatar?w=400&h=400&u=3" />      <Avatar.Fallback xstyle={s.roundLg}>JD</Avatar.Fallback>    </Avatar>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

全局 CSS

可使用 @layer components 指令自定义 Avatar 组件类。 了解更多。

@layer components {  .avatar {    @apply size-16 border-2 border-accent;  }
  .avatar__fallback {    @apply bg-gradient-to-br from-purple-500 to-pink-500;  }}

样式参考

HeroUI 遵循 BEM 方法论，确保组件变体与状态可复用且易于自定义。

CSS 类

Avatar 组件使用以下 CSS 类（查看源码样式）：

基础类 [!toc]

  • .avatar - 基础容器，默认尺寸（size-10）
  • .avatar__image - 图片元素，aspect-square 尺寸
  • .avatar__fallback - 居中内容的 fallback 容器

尺寸修饰符 [!toc]

  • .avatar--sm - 小头像（size-8）
  • .avatar--md - 中头像（默认，无额外样式）
  • .avatar--lg - 大头像（size-12）

变体修饰符 [!toc]

  • .avatar--soft - 浅色背景的 soft 变体

颜色修饰符 [!toc]

  • .avatar__fallback--default - 默认文字颜色
  • .avatar__fallback--accent - 强调色文字
  • .avatar__fallback--success - 成功色文字
  • .avatar__fallback--warning - 警告色文字
  • .avatar__fallback--danger - 危险色文字

API 参考

Avatar

Prop类型默认值描述
size'sm' | 'md' | 'lg''md'头像尺寸
color'default' | 'accent' | 'success' | 'warning' | 'danger''default'Fallback 颜色主题
variant'default' | 'soft''default'视觉样式变体
classNamestring-附加 CSS 类

Avatar.Image

Prop类型默认值描述
srcstring-图片 URL
srcSetstring-响应式图片的 srcset 属性
sizesstring-响应式图片的 sizes 属性
altstring-图片替代文本
asChildbooleanfalse将属性合并到子元素上（例如 next/image），而不是渲染原生 img
onLoad(event: SyntheticEvent<HTMLImageElement>) => void-图片加载成功时的回调
onError(event: SyntheticEvent<HTMLImageElement>) => void-图片加载失败时的回调
crossOrigin'anonymous' | 'use-credentials'-图片请求的 CORS 设置
loading'eager' | 'lazy'-原生懒加载属性
classNamestring-附加 CSS 类

Avatar.Fallback

Prop类型默认值描述
delayMsnumber-显示 fallback 前的延迟（防止闪烁）
color'default' | 'accent' | 'success' | 'warning' | 'danger'-覆盖父级颜色
classNamestring-附加 CSS 类

相关组件

AvatarGroup 头像组

以叠放或网格展示多个头像，并支持溢出计数

Separator 分隔符

在内容区块之间进行视觉分隔。

Badge 徽章

相对其他元素定位的小型指示器，常用于通知数量、状态点与标签