# Avatar **Category**: react **URL**: https://www.heroui.com/docs/react/components/avatar **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(media)/avatar.mdx > Display user profile images with customizable fallback content *** ## Import ```tsx import { Avatar } from '@heroui/react'; ``` ### Usage ```tsx import {Avatar} from "@heroui/react"; export function Basic() { return (
JD B JR
); } ``` ### Anatomy Import the Avatar component and access all parts using dot notation. ```tsx import { Avatar } from '@heroui/react'; export default () => ( ) ``` ### Sizes ```tsx import {Avatar} from "@heroui/react"; export function Sizes() { return (
SM MD LG
); } ``` ### Colors ```tsx import {Avatar} from "@heroui/react"; export function Colors() { return (
DF AC SC WR DG
); } ``` ### Variants ```tsx import {Person} from "@gravity-ui/icons"; import {Avatar, Separator} from "@heroui/react"; 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: , label: "icon", type: "icon"}, {content: , 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 (
{/* Color labels header */}
{colors.map((color) => (
{color}
))}
{/* Variant rows */} {variants.map((variant) => (
{variant.label}
{colors.map((color, colorIndex) => (
{variant.type === "img" ? ( <> {color.charAt(0).toUpperCase()} ) : ( {variant.content} )}
))}
))}
); } ``` ### Fallback Content ```tsx import {Person} from "@gravity-ui/icons"; import {Avatar} from "@heroui/react"; export function Fallback() { return (
{/* Text fallback */} JD {/* Icon fallback */} {/* Fallback with delay */} NA {/* Custom styled fallback */} GB
); } ``` ### Avatar Group ```tsx import {Avatar} from "@heroui/react"; const users = [ { id: 1, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg", name: "John Doe", }, { id: 2, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg", name: "Kate Wilson", }, { id: 3, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg", name: "Emily Chen", }, { id: 4, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg", name: "Michael Brown", }, { id: 5, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg", name: "Olivia Davis", }, ]; export function Group() { return (
{/* Basic avatar group */}
{users.slice(0, 4).map((user) => ( {user.name .split(" ") .map((n) => n[0]) .join("")} ))}
{/* Avatar group with counter */}
{users.slice(0, 3).map((user) => ( {user.name .split(" ") .map((n) => n[0]) .join("")} ))} +{users.length - 3}
); } ``` ### Custom Styles ```tsx import {Avatar} from "@heroui/react"; export function CustomStyles() { return (
{/* Custom size with Tailwind classes */} XL {/* Square avatar */} SQ {/* Gradient border */}
GB
{/* Status indicator */}
ON
); } ``` ## Related Components - **Separator**: Visual divider between content - **Badge**: Small indicator positioned relative to another element ## Styling ### Passing Tailwind CSS classes ```tsx import { Avatar } from '@heroui/react'; function CustomAvatar() { return ( XL ); } ``` ### Customizing the component classes To customize the Avatar component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @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](https://getbem.com/) 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](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/avatar.css)): #### 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 | 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 Props | 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 | | `onLoad` | `(event: SyntheticEvent) => void` | - | Callback when the image loads successfully | | `onError` | `(event: SyntheticEvent) => 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 Props | 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 |