# Avatar **Category**: react **URL**: https://www.heroui.com/docs/react/migration/avatar **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/migration/(components)/avatar.mdx > Migration guide for Avatar from HeroUI v2 to v3 *** Refer to the [v3 Avatar documentation](/docs/react/components/avatar) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2. ## Structure Changes In v2, `Avatar` was a single component that accepted props for image source, name, fallback, and other elements: ```tsx import { Avatar } from "@heroui/react"; export default function App() { return ( ); } ``` In v3, Avatar uses a compound component pattern with explicit subcomponents: ```tsx import { Avatar } from "@heroui/react"; export default function App() { return ( JD ); } ``` ## Key Changes ### 1. Component Structure **v2:** Single `Avatar` component with props **v3:** Compound components: `Avatar`, `Avatar.Image`, `Avatar.Fallback` ### 2. Prop Changes | v2 Prop | v3 Location | Notes | |---------|-------------|-------| | `src` | `Avatar.Image` | Use `` | | `name` | - | Generate initials and pass to `` | | `showFallback` | - | Removed (fallback shown if image fails or not provided) | | `fallback`, `icon` | `Avatar.Fallback` | Place content in `` | | `color` | `Avatar` | Same; `primary` → `accent`, `secondary` → `default` | | `variant` | `Avatar` | New in v3; `"default"` \| `"soft"` | | `size` | `Avatar` | Same | | `isBordered` | - | Removed (use Tailwind e.g. `ring-2 ring-background`) | | `radius` | - | Removed (use Tailwind e.g. `rounded-full`) | | `isDisabled`, `isFocusable` | - | Removed (use Tailwind / `asChild` if needed) | | `getInitials` | - | Generate initials manually | | `ImgComponent`, `imgProps` | - | Use `asChild` on `Avatar.Image` if needed | | `onError` | `Avatar.Image` | Use `onError` on `` | | - | `Avatar.Image` | New: `srcSet`, `sizes`, `loading` for responsive images | | - | `Avatar.Fallback` | New: `delayMs` to delay fallback display (prevents flash) | | `classNames` | - | Use `className` on parts | | AvatarGroup | - | No v3 equivalent; create groups with CSS | ### 3. Variant Prop (New in v3) **v2:** No `variant` prop; styling controlled only through `color` **v3:** New `variant` prop with `"default"` and `"soft"` options. The `"soft"` variant applies a lighter background style. ```tsx JD ``` ### 4. Avatar.Image Responsive Attributes (New in v3) **v2:** Limited to `src` and `onError` **v3:** `Avatar.Image` now supports `srcSet`, `sizes`, and `loading` for responsive image handling ```tsx JD ``` ### 5. Avatar.Fallback `delayMs` Prop (New in v3) **v2:** Fallback shown immediately or controlled via `showFallback` **v3:** `Avatar.Fallback` supports a `delayMs` prop to delay rendering, preventing flash of fallback content when images load quickly ```tsx JD ``` ### 6. Image and Fallback Handling **v2:** Used `src`, `name`, `showFallback`, and `fallback` props **v3:** Must explicitly render `` and `` components ### 7. Color Props | v2 Color | v3 Color | Notes | |----------|---------|-------| | `default` | `default` | Same | | `primary` | `accent` | Renamed | | `secondary` | `default` | Use `default` color | | `success` | `success` | Same | | `warning` | `warning` | Same | | `danger` | `danger` | Same | ### 8. AvatarGroup Removed **v2:** Had a dedicated `AvatarGroup` component **v3:** No `AvatarGroup` component - create groups manually with CSS classes ## Migration Examples ### Sizes and Colors ```tsx ``` ```tsx J ``` ### Custom Fallback ```tsx import { Icon } from "@iconify/react"; } /> ``` ```tsx import { Icon } from "@iconify/react"; ``` ### Avatar Group ```tsx import { Avatar, AvatarGroup } from "@heroui/react"; ``` ```tsx import { Avatar } from "@heroui/react";
U1 U2 U3
``` ### Avatar Group with Max Count ```tsx import { Avatar, AvatarGroup } from "@heroui/react"; ``` ```tsx import { Avatar } from "@heroui/react"; const users = [ { id: 1, src: "https://example.com/1.jpg", name: "User 1" }, { id: 2, src: "https://example.com/2.jpg", name: "User 2" }, { id: 3, src: "https://example.com/3.jpg", name: "User 3" }, { id: 4, src: "https://example.com/4.jpg", name: "User 4" }, { id: 5, src: "https://example.com/5.jpg", name: "User 5" }, ];
{users.slice(0, 3).map((user) => ( {user.name.split(" ").map(n => n[0]).join("")} ))} +{users.length - 3}
``` ### Variants ```tsx {/* v2 doesn't have variants, but uses color prop */} ``` ```tsx {/* v3 has variant prop */} J ``` ## Styling Changes ### v2: `classNames` Prop ```tsx ``` ### v3: Direct `className` Props ```tsx JD ``` ## Component Anatomy The v3 Avatar follows this structure: ``` Avatar (Root) ├── Avatar.Image (optional) └── Avatar.Fallback (optional; shown when image fails or not provided) ``` ## Helper Function for Initials Since v3 doesn't have a `name` prop, you'll need to generate initials manually: ```tsx function getInitials(name: string): string { return name .split(" ") .map(n => n[0]) .join("") .toUpperCase() .slice(0, 2); } // Usage {getInitials("John Doe")} ``` ## Summary 1. **Component Structure**: Must use compound components (`Avatar.Image`, `Avatar.Fallback`) 2. **Name Prop Removed**: Generate initials manually 3. **ShowFallback Removed**: Fallback always shows if image fails 4. **Variant Prop Added**: New `variant` prop (`"default"` | `"soft"`) for visual style control 5. **Responsive Image Support**: `Avatar.Image` now supports `srcSet`, `sizes`, and `loading` attributes 6. **Fallback Delay**: `Avatar.Fallback` supports `delayMs` to prevent flash of fallback content 7. **Color Mapping**: `primary` → `accent`, `secondary` → `default` 8. **Bordered Removed**: Use Tailwind `ring-2 ring-background` classes 9. **Radius Removed**: Use Tailwind `rounded-*` classes 10. **Disabled Removed**: Use Tailwind `opacity-50` classes 11. **AvatarGroup Removed**: Create groups manually with CSS 12. **Icon Prop Removed**: Place icon content in `Avatar.Fallback` 13. **ClassNames Removed**: Use `className` props on individual components