Avatar

An Avatar is a visual representation of a user or entity, typically shown as an image, initials, or icon.

Use Avatars to personalize interfaces, indicate user presence, or represent participants, ideal for profiles, comments, chat UIs, or team lists.

Common alternative names:
Profile Picture, Display Image

---

Variants

---

Sizes

Preview

Code

Row(
  spacing: 8,
  mainAxisAlignment: MainAxisAlignment.center,
  children: [
    Avatar(
      image: 'https://picsum.photos/200',
      size: AvatarSize.xs, // 24px
    ),
    Avatar(
      image: 'https://picsum.photos/200',
      size: AvatarSize.sm, // 32px
    ),
    Avatar(
      image: 'https://picsum.photos/200',
      size: AvatarSize.md, // 40px
    ),
    Avatar(
      image: 'https://picsum.photos/200',
      size: AvatarSize.lg, // 48px
    ),
    Avatar(
      image: 'https://picsum.photos/200',
      size: AvatarSize.xl, // 64px
    ),
    Avatar(
      image: 'https://picsum.photos/200',
      size: AvatarSize.xxl, // 80px
    ),
  ],
)

Avatar with Name

Shows a person’s photo next to their name for clear identification.

Preview

Code

Avatar.meta(
  size: AvatarSize.lg,
  title: 'James Ryan',
  image: 'https://picsum.photos/200',
)

---

Avatar with Name and Sub-Label

Displays several avatars together to represent a group, participants, or shared activity.

Preview

Code

Avatar.meta(
  size: AvatarSize.lg,
  title: 'James Ryan',
  subtitle: 'Product Design',
  image: 'https://picsum.photos/200',
)

---

Avatar Group

Pairs a group of avatars with a label that indicates additional members (e.g., “+72 others”).

Preview

Code

Avatar.stacked(
  images: List.filled(5, 'https://picsum.photos/200'),
)

---

Avatar Group with Label

Shows a few avatars overlapping with a counter for the rest, ideal for compact layouts or limited space.

Preview

Code

Avatar.stacked(
  label: 'and 72 others',
  images: List.filled(5, 'https://picsum.photos/200'),
)

---

Stacked Avatars

Shows a limited number of avatars followed by a counter. Use when space is constrained.

Preview

Code

Avatar.stacked(
  limit: 3,
  images: List.filled(10, 'https://picsum.photos/200'),
)

---

Avatar with Indicator

Avatar with a custom badge indicator, such as icons for status, verification, or other visual markers.

Preview

Code

Row(
  spacing: 12,
  mainAxisAlignment: MainAxisAlignment.center,
  children: [
    const Avatar(
      size: AvatarSize.lg,
      image: 'https://picsum.photos/200',
    ),
    const Badges(
      size: BadgeSize.small,
      alignment: Alignment.bottomRight,
      child: Avatar(
        size: AvatarSize.lg,
        image: 'https://picsum.photos/200',
      ),
    ),
    Badges(
      alignment: Alignment.bottomRight,
      badgeContent: Image.asset(
        'assets/company.png',
        width: 16,
      ),
      child: const Avatar(
        size: AvatarSize.lg,
        image: 'https://picsum.photos/200',
      ),
    ),
    Badges(
      alignment: Alignment.bottomRight,
      badgeContent: SvgPicture.asset(
        'assets/verified.svg',
        width: 16,
      ),
      child: const Avatar(
        size: AvatarSize.lg,
        image: 'https://picsum.photos/200',
      ),
    ),
  ],
),

---

Error Handling

The Avatar component automatically handles image loading errors by displaying a fallback:

1. Default fallback shows a person icon
2. Custom fallback can be provided via errorImage
3. Maintains consistent size and shape

Preview

Code

Row(
  spacing: 16,
  mainAxisAlignment: MainAxisAlignment.center,
  children: [
    // Default error fallback
    Avatar(
      image: 'invalid-url.jpg',
      size: AvatarSize.lg,
    ),
    // Custom icon fallback
    Avatar(
      image: 'invalid-url.jpg',
      size: AvatarSize.lg,
      errorImage: Icon(Icons.circle),
    ),
    // Custom text fallback
    Avatar(
      image: 'invalid-url.jpg',
      size: AvatarSize.lg,
      errorImage: Text('N'),
    ),
  ],
)

---

Properties

Property	Type	Description
image	String	URL or asset path of the avatar image
errorImage	Widget?	Widget to display when image fails to load
size	AvatarSize	Predefined size of the avatar (xs, sm, md, lg, xl, xxl)
backgroundColor	Color?	Background color of the avatar

Meta Layout Properties

Property	Type	Description
title	String	Primary text displayed next to avatar
subtitle	String?	Secondary text displayed below title
titleStyle	TextStyle?	Custom style for title text
subtitleStyle	TextStyle?	Custom style for subtitle text

Stacked Layout Properties

Property	Type	Description
images	List<String>	List of image URLs or paths to display
limit	int	Maximum number of visible avatars
label	String?	Text to display after the stack
counterStyle	TextStyle?	Style for the overflow counter