Anatomy

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

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

Examples

Variants

accent

default

success

warning

danger

letter

letter soft

icon

icon soft

img

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.

Tailwind CSS

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

.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

Prop	Type	Default	Description
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Avatar size
`color`	`'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'`	`'default'`	Fallback color theme
`variant`	`'default' \| 'soft'`	`'default'`	Visual style variant
`className`	`string`	-	Additional CSS classes

Avatar.Image

Prop	Type	Default	Description
`src`	`string`	-	Image source URL
`srcSet`	`string`	-	The image `srcset` attribute for responsive images
`sizes`	`string`	-	The image `sizes` attribute for responsive images
`alt`	`string`	-	Alternative text for the image
`asChild`	`boolean`	`false`	Merge 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
`className`	`string`	-	Additional CSS classes

Avatar.Fallback

Prop	Type	Default	Description
`delayMs`	`number`	-	Delay before showing fallback (prevents flash)
`color`	`'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'`	-	Override color from parent
`className`	`string`	-	Additional CSS classes