HeroUI

Avatar

Display user profile images with customizable fallback content

FigmaStorybookRadix UISourceStyles source

Import

import { Avatar } from '@heroui/react';

Usage

John DoeJDBlueBJR
"use client";

import {Avatar} from "@heroui/react";

export function Basic() {
  return (
    <div className="flex items-center gap-4">
      <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>
  );
}

Anatomy

Import all parts and piece them together.

import { Avatar } from '@heroui/react';

export default () => (
  <Avatar>
    <Avatar.Image/>
    <Avatar.Fallback/>
  </Avatar>
)

Sizes

Small AvatarSMMedium AvatarMDLarge AvatarLG
"use client";

import {Avatar} from "@heroui/react";

export function Sizes() {
  return (
    <div className="flex items-center gap-4">
      <Avatar size="sm">
        <Avatar.Image
          alt="Small Avatar"
          src="https://img.heroui.chat/image/avatar?w=400&h=400&u=3"
        />
        <Avatar.Fallback>SM</Avatar.Fallback>
      </Avatar>
      <Avatar size="md">
        <Avatar.Image
          alt="Medium Avatar"
          src="https://img.heroui.chat/image/avatar?w=400&h=400&u=4"
        />
        <Avatar.Fallback>MD</Avatar.Fallback>
      </Avatar>
      <Avatar size="lg">
        <Avatar.Image
          alt="Large Avatar"
          src="https://img.heroui.chat/image/avatar?w=400&h=400&u=5"
        />
        <Avatar.Fallback>LG</Avatar.Fallback>
      </Avatar>
    </div>
  );
}

Colors

DFACSCWRDG
"use client";

import {Avatar} from "@heroui/react";

export function Colors() {
  return (
    <div className="flex items-center gap-4">
      <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>
  );
}

Fallback Content

JDDelayed AvatarGB
"use client";

import {Avatar} from "@heroui/react";
import {Icon} from "@iconify/react";

export function Fallback() {
  return (
    <div className="flex items-center gap-4">
      {/* Text fallback */}
      <Avatar>
        <Avatar.Fallback>JD</Avatar.Fallback>
      </Avatar>

      {/* Icon fallback */}
      <Avatar>
        <Avatar.Fallback>
          <Icon icon="gravity-ui:person" />
        </Avatar.Fallback>
      </Avatar>

      {/* Fallback with delay */}
      <Avatar>
        <Avatar.Image
          alt="Delayed Avatar"
          src="https://invalid-url-to-show-fallback.com/image.jpg"
        />
        <Avatar.Fallback delayMs={600}>NA</Avatar.Fallback>
      </Avatar>

      {/* Custom styled fallback */}
      <Avatar>
        <Avatar.Fallback className="border-none bg-gradient-to-br from-pink-500 to-purple-500 text-white">
          GB
        </Avatar.Fallback>
      </Avatar>
    </div>
  );
}

Avatar Group

John DoeJDKate WilsonKWEmily ChenECMichael BrownMB
John DoeJDKate WilsonKWEmily ChenEC+2
"use client";

import {Avatar} from "@heroui/react";

const users = [
  {
    id: 1,
    image: "https://img.heroui.chat/image/avatar?w=400&h=400&u=3",
    name: "John Doe",
  },
  {
    id: 2,
    image: "https://img.heroui.chat/image/avatar?w=400&h=400&u=5",
    name: "Kate Wilson",
  },
  {
    id: 3,
    image: "https://img.heroui.chat/image/avatar?w=400&h=400&u=20",
    name: "Emily Chen",
  },
  {
    id: 4,
    image: "https://img.heroui.chat/image/avatar?w=400&h=400&u=23",
    name: "Michael Brown",
  },
  {
    id: 5,
    image: "https://img.heroui.chat/image/avatar?w=400&h=400&u=16",
    name: "Olivia Davis",
  },
];

export function Group() {
  return (
    <div className="flex flex-col gap-6">
      {/* Basic avatar group */}
      <div className="flex -space-x-2">
        {users.slice(0, 4).map((user) => (
          <Avatar key={user.id} className="ring-background ring-2">
            <Avatar.Image alt={user.name} src={user.image} />
            <Avatar.Fallback>
              {user.name
                .split(" ")
                .map((n) => n[0])
                .join("")}
            </Avatar.Fallback>
          </Avatar>
        ))}
      </div>

      {/* Avatar group with counter */}
      <div className="flex -space-x-2">
        {users.slice(0, 3).map((user) => (
          <Avatar key={user.id} className="ring-background ring-2">
            <Avatar.Image alt={user.name} src={user.image} />
            <Avatar.Fallback>
              {user.name
                .split(" ")
                .map((n) => n[0])
                .join("")}
            </Avatar.Fallback>
          </Avatar>
        ))}
        <Avatar className="ring-background ring-2">
          <Avatar.Fallback className="text-xs">+{users.length - 3}</Avatar.Fallback>
        </Avatar>
      </div>
    </div>
  );
}

Custom Styles

Extra LargeXLSquare AvatarSQ
Gradient BorderGB
Online UserON
"use client";

import {Avatar} from "@heroui/react";

export function CustomStyles() {
  return (
    <div className="flex items-center gap-4">
      {/* Custom size with Tailwind classes */}
      <Avatar className="size-16">
        <Avatar.Image
          alt="Extra Large"
          src="https://img.heroui.chat/image/avatar?w=400&h=400&u=3"
        />
        <Avatar.Fallback>XL</Avatar.Fallback>
      </Avatar>

      {/* Square avatar */}
      <Avatar className="rounded-lg">
        <Avatar.Image
          alt="Square Avatar"
          src="https://img.heroui.chat/image/avatar?w=400&h=400&u=4"
        />
        <Avatar.Fallback className="rounded-lg">SQ</Avatar.Fallback>
      </Avatar>

      {/* Gradient border */}
      <Avatar className="bg-gradient-to-tr from-pink-500 to-yellow-500 p-0.5">
        <div className="bg-background size-full rounded-full p-0.5">
          <Avatar.Image
            alt="Gradient Border"
            className="rounded-full"
            src="https://img.heroui.chat/image/avatar?w=400&h=400&u=5"
          />
          <Avatar.Fallback className="border-none">GB</Avatar.Fallback>
        </div>
      </Avatar>

      {/* Status indicator */}
      <div className="relative">
        <Avatar>
          <Avatar.Image
            alt="Online User"
            src="https://img.heroui.chat/image/avatar?w=400&h=400&u=8"
          />
          <Avatar.Fallback>ON</Avatar.Fallback>
        </Avatar>
        <span className="ring-background absolute bottom-0 right-0 size-3 rounded-full bg-green-500 ring-2" />
      </div>
    </div>
  );
}

Styling

Passing Tailwind CSS classes

import { Avatar } from '@heroui/react';

function CustomAvatar() {
  return (
    <Avatar className="size-20">
      <Avatar.Image src="..." alt="..." />
      <Avatar.Fallback>XL</Avatar.Fallback>
    </Avatar>
  );
}

Customizing the component classes

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

@layer components {
  .avatar {
    @apply size-16 border-2 border-primary;
  }

  .avatar__fallback {
    @apply bg-gradient-to-br from-purple-500 to-pink-500;
  }
}

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

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

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

Color Modifiers

  • .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 Props

PropTypeDefaultDescription
size'sm' | 'md' | 'lg''md'Avatar size
color'default' | 'accent' | 'success' | 'warning' | 'danger''default'Fallback color theme
classNamestring-Additional CSS classes
asChildbooleanfalseRender as child element

Avatar.Image Props

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
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
onLoadingStatusChange(status: 'loading' | 'loaded' | 'pending' | 'failed') => void-Callback for loading status changes
ignoreFallbackbooleanfalseIf true, opt out of the fallback logic and use as regular img
shouldBypassImageLoadbooleanfalseIf true, image load will be bypassed and handled by asChild component
crossOrigin'anonymous' | 'use-credentials'-CORS setting for the image request
loading'eager' | 'lazy'-Native lazy loading attribute
classNamestring-Additional CSS classes
asChildbooleanfalseRender as child element

Avatar.Fallback Props

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

Accordion

A collapsible content panel for organizing information in a compact space

Button

A clickable button component with multiple variants and states