Avatar

Import

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

Usage

Anatomy

Import the Avatar component and access all parts using dot notation.

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

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

Sizes

Colors

Variants

Fallback Content

Avatar Group

Custom Styles

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.

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)

Variant Modifiers

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

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

Avatar.Image Props

Avatar.Fallback Props