Avatar

Migration guide for Avatar from HeroUI v2 to v3

Refer to the v3 Avatar documentation 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:

1import { Avatar } from "@lenso/ui";2
3export default function App() {4  return (5    <Avatar 6      src="https://example.com/avatar.jpg"7      name="John Doe"8      showFallback9    />10  );11}

In v3, Avatar uses a compound component pattern with explicit subcomponents:

1import { Avatar } from "@lenso/ui";2
3export default function App() {4  return (5    <Avatar>6      <Avatar.Image src="https://example.com/avatar.jpg" alt="John Doe" />7      <Avatar.Fallback>JD</Avatar.Fallback>8    </Avatar>9  );10}

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 `<Avatar.Image src="..." />`
`name`	-	Generate initials and pass to `<Avatar.Fallback />`
`showFallback`	-	Removed (fallback shown if image fails or not provided)
`fallback`, `icon`	`Avatar.Fallback`	Place content in `<Avatar.Fallback />`
`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 />`
-	`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	`AvatarGroup`	Available again — compound `Avatar` children with `max` / `color` / `variant` / `isGrid` / `overlap` (`clip`\|`ring`) and optional `AvatarGroup.Count`; v2 `total` → explicit `Count`; see AvatarGroup

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.

1<Avatar variant="soft" color="accent">2  <Avatar.Image src="..." alt="User" />3  <Avatar.Fallback>JD</Avatar.Fallback>4</Avatar>

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

1<Avatar>2  <Avatar.Image3    src="avatar-400.jpg"4    srcSet="avatar-200.jpg 200w, avatar-400.jpg 400w"5    sizes="(max-width: 600px) 200px, 400px"6    loading="lazy"7    alt="User"8  />9  <Avatar.Fallback>JD</Avatar.Fallback>10</Avatar>

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

1<Avatar>2  <Avatar.Image src="..." alt="User" />3  <Avatar.Fallback delayMs={600}>JD</Avatar.Fallback>4</Avatar>

6. Image and Fallback Handling

v2: Used src, name, showFallback, and fallback props
v3: Must explicitly render <Avatar.Image /> and <Avatar.Fallback /> 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 (Available in v3)

v2: Dedicated AvatarGroup with props like isBordered, max, and total
v3: AvatarGroup is available again as a dedicated component. Wrap compound Avatar children, inherit size / color / variant via context, and use max, isGrid, and overlap ("clip" default, or "ring"). v2 total is removed — render an explicit AvatarGroup.Count child for a known server total (it suppresses the auto count from max). isBordered is removed; use Tailwind or overlap="ring". See the AvatarGroup docs.

1import { Avatar, AvatarGroup } from "@lenso/ui";2
3<AvatarGroup max={3} size="md">4  <Avatar>5    <Avatar.Image src="https://example.com/1.jpg" alt="User 1" />6    <Avatar.Fallback>U1</Avatar.Fallback>7  </Avatar>8  <Avatar>9    <Avatar.Image src="https://example.com/2.jpg" alt="User 2" />10    <Avatar.Fallback>U2</Avatar.Fallback>11  </Avatar>12  <Avatar>13    <Avatar.Image src="https://example.com/3.jpg" alt="User 3" />14    <Avatar.Fallback>U3</Avatar.Fallback>15  </Avatar>16  <Avatar>17    <Avatar.Image src="https://example.com/4.jpg" alt="User 4" />18    <Avatar.Fallback>U4</Avatar.Fallback>19  </Avatar>20</AvatarGroup>

Migration Examples

Sizes and Colors

1<Avatar size="md" color="primary" src="..." name="John" />

Custom Fallback

1import { Icon } from "@iconify/react";2
3<Avatar 4  src="https://broken-url.com/image.jpg"5  showFallback6  fallback={<Icon icon="mdi:account" />}7/>

Avatar Group

1import { Avatar, AvatarGroup } from "@lenso/ui";2
3<AvatarGroup isBordered>4  <Avatar src="https://example.com/1.jpg" />5  <Avatar src="https://example.com/2.jpg" />6  <Avatar src="https://example.com/3.jpg" />7</AvatarGroup>

Avatar Group with Max Count

1import { Avatar, AvatarGroup } from "@lenso/ui";2
3<AvatarGroup max={3}>4  <Avatar src="https://example.com/1.jpg" />5  <Avatar src="https://example.com/2.jpg" />6  <Avatar src="https://example.com/3.jpg" />7  <Avatar src="https://example.com/4.jpg" />8  <Avatar src="https://example.com/5.jpg" />9</AvatarGroup>

Avatar Group Total → Count

1import { Avatar, AvatarGroup } from "@lenso/ui";2
3<AvatarGroup max={3} total={12}>4  <Avatar src="https://example.com/1.jpg" />5  <Avatar src="https://example.com/2.jpg" />6  <Avatar src="https://example.com/3.jpg" />7</AvatarGroup>

Variants

1{/* v2 doesn't have variants, but uses color prop */}2<Avatar color="primary" name="John" />

Styling Changes

v2: `classNames` Prop

1<Avatar 2  classNames={{3    base: "custom-base",4    img: "custom-img",5    fallback: "custom-fallback"6  }}7/>

v3: Direct `className` Props

1<Avatar className="custom-base">2  <Avatar.Image className="custom-img" src="..." alt="..." />3  <Avatar.Fallback className="custom-fallback">4    JD5  </Avatar.Fallback>6</Avatar>

Component Anatomy

The v3 Avatar follows this structure:

1Avatar (Root)2  ├── Avatar.Image (optional)3  └── 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:

1function getInitials(name: string): string {2  return name3    .split(" ")4    .map(n => n[0])5    .join("")6    .toUpperCase()7    .slice(0, 2);8}9
10// Usage11<Avatar>12  <Avatar.Fallback>{getInitials("John Doe")}</Avatar.Fallback>13</Avatar>

Summary

Component Structure: Must use compound components (Avatar.Image, Avatar.Fallback)
Name Prop Removed: Generate initials manually
ShowFallback Removed: Fallback always shows if image fails
Variant Prop Added: New variant prop ("default" | "soft") for visual style control
Responsive Image Support: Avatar.Image now supports srcSet, sizes, and loading attributes
Fallback Delay: Avatar.Fallback supports delayMs to prevent flash of fallback content
Color Mapping: primary → accent, secondary → default
Bordered Removed: Use Tailwind ring-2 ring-background classes
Radius Removed: Use Tailwind rounded-* classes
Disabled Removed: Use Tailwind opacity-50 classes
AvatarGroup Available: Use the dedicated AvatarGroup component (docs) with compound Avatar children, max / overlap / isGrid, and optional AvatarGroup.Count (replaces v2 total)
Icon Prop Removed: Place icon content in Avatar.Fallback
ClassNames Removed: Use className props on individual components