HeroUI

Avatar

Display user profile images with customizable fallback content

FigmaStorybookRadix UISourceStyles source

Import

import { Avatar, AvatarImage, AvatarFallback } from '@heroui/react';

Usage

JDBJR
"use client";

import {Avatar, AvatarFallback, AvatarImage} from "@heroui/react";

export function Basic() {
  return (
    <div className="flex items-center gap-4">
      <Avatar>
        <AvatarImage alt="John Doe" src="https://img.heroui.chat/image/avatar?w=400&h=400&u=3" />
        <AvatarFallback>JD</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarImage
          alt="Blue"
          src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
        />
        <AvatarFallback>B</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarFallback>JR</AvatarFallback>
      </Avatar>
    </div>
  );
}

Anatomy

Import all parts and piece them together.

import { Avatar, AvatarImage, AvatarFallback } from '@heroui/react';

export default () => (
  <Avatar>
    <AvatarImage/>
    <AvatarFallback/>
  </Avatar>
)

Sizes

SMMDLG
"use client";

import {Avatar, AvatarFallback, AvatarImage} from "@heroui/react";

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

Colors

DFACSCWRDG
"use client";

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

export function Colors() {
  return (
    <div className="flex items-center gap-4">
      <Avatar color="default">
        <AvatarFallback>DF</AvatarFallback>
      </Avatar>
      <Avatar color="accent">
        <AvatarFallback>AC</AvatarFallback>
      </Avatar>
      <Avatar color="success">
        <AvatarFallback>SC</AvatarFallback>
      </Avatar>
      <Avatar color="warning">
        <AvatarFallback>WR</AvatarFallback>
      </Avatar>
      <Avatar color="danger">
        <AvatarFallback>DG</AvatarFallback>
      </Avatar>
    </div>
  );
}

Fallback Content

JDGB
"use client";

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

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

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

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

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

Avatar Group

JDKWECMB
JDKWEC+2
"use client";

import {Avatar, AvatarFallback, AvatarImage} 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">
            <AvatarImage alt={user.name} src={user.image} />
            <AvatarFallback>
              {user.name
                .split(" ")
                .map((n) => n[0])
                .join("")}
            </AvatarFallback>
          </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">
            <AvatarImage alt={user.name} src={user.image} />
            <AvatarFallback>
              {user.name
                .split(" ")
                .map((n) => n[0])
                .join("")}
            </AvatarFallback>
          </Avatar>
        ))}
        <Avatar className="ring-background ring-2">
          <AvatarFallback className="text-xs">+{users.length - 3}</AvatarFallback>
        </Avatar>
      </div>
    </div>
  );
}

Custom Styles

XLSQ
GB
ON
"use client";

import {Avatar, AvatarFallback, AvatarImage} from "@heroui/react";

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

      {/* Square avatar */}
      <Avatar className="rounded-lg">
        <AvatarImage
          alt="Square Avatar"
          src="https://img.heroui.chat/image/avatar?w=400&h=400&u=4"
        />
        <AvatarFallback className="rounded-lg">SQ</AvatarFallback>
      </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">
          <AvatarImage
            alt="Gradient Border"
            className="rounded-full"
            src="https://img.heroui.chat/image/avatar?w=400&h=400&u=5"
          />
          <AvatarFallback className="border-none">GB</AvatarFallback>
        </div>
      </Avatar>

      {/* Status indicator */}
      <div className="relative">
        <Avatar>
          <AvatarImage
            alt="Online User"
            src="https://img.heroui.chat/image/avatar?w=400&h=400&u=8"
          />
          <AvatarFallback>ON</AvatarFallback>
        </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, AvatarImage, AvatarFallback } from '@heroui/react';

function CustomAvatar() {
  return (
    <Avatar className="size-20">
      <AvatarImage src="..." alt="..." />
      <AvatarFallback>XL</AvatarFallback>
    </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

AvatarImage 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

AvatarFallback 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