Skip to content
Lenso UI

Avatar

Display user profile images with customizable fallback content

Usage

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.

Anatomy

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

Examples

Sizes

"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.

Colors

"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.

Variants

"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.

Fallback Content

"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.

Customization

Custom Image Component

Use asChild on Avatar.Image to compose with a custom image component. This example uses Next.js Image for optimized loading. Pass src on Avatar.Image so it can track the loading state and show the fallback until the image is ready.

"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.

Global CSS

To customize the Avatar component classes, you can use the @layer components directive. Learn more.

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

Styling Reference

HeroUI follows the BEM methodology to ensure component variants and states are reusable and easy to customize.

CSS Classes

The Avatar component uses these CSS classes (View source styles):

Base Classes [!toc]

  • .avatar - Base container with default size (size-10)
  • .avatar__image - Image element with aspect-square sizing
  • .avatar__fallback - Fallback container with centered content

Size Modifiers [!toc]

  • .avatar--sm - Small avatar (size-8)
  • .avatar--md - Medium avatar (default, no additional styles)
  • .avatar--lg - Large avatar (size-12)

Variant Modifiers [!toc]

  • .avatar--soft - Soft variant with lighter background

Color Modifiers [!toc]

  • .avatar__fallback--default - Default text color
  • .avatar__fallback--accent - Accent text color
  • .avatar__fallback--success - Success text color
  • .avatar__fallback--warning - Warning text color
  • .avatar__fallback--danger - Danger text color

API Reference

Avatar

PropTypeDefaultDescription
size'sm' | 'md' | 'lg''md'Avatar size
color'default' | 'accent' | 'success' | 'warning' | 'danger''default'Fallback color theme
variant'default' | 'soft''default'Visual style variant
classNamestring-Additional CSS classes

Avatar.Image

PropTypeDefaultDescription
srcstring-Image source URL
srcSetstring-The image srcset attribute for responsive images
sizesstring-The image sizes attribute for responsive images
altstring-Alternative text for the image
asChildbooleanfalseMerge props onto the child element (e.g. next/image) instead of rendering a native img
onLoad(event: SyntheticEvent<HTMLImageElement>) => void-Callback when the image loads successfully
onError(event: SyntheticEvent<HTMLImageElement>) => void-Callback when there's an error loading the image
crossOrigin'anonymous' | 'use-credentials'-CORS setting for the image request
loading'eager' | 'lazy'-Native lazy loading attribute
classNamestring-Additional CSS classes

Avatar.Fallback

PropTypeDefaultDescription
delayMsnumber-Delay before showing fallback (prevents flash)
color'default' | 'accent' | 'success' | 'warning' | 'danger'-Override color from parent
classNamestring-Additional CSS classes
AvatarGroup

Display a stacked or grid group of avatars with overflow counting

Separator

Visually divide content sections

Badge

Displays a small indicator positioned relative to another element, commonly used for notification counts, status dots, and labels