For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/en/components/avatar.md.

AvatarGroup

Display member avatars together, with text fallbacks and overflow counts. Use Avatar for each member.

Basic usage

Place member avatars inside AvatarGroup and provide each member name through Avatar.alt.

basic.tsx
import { Avatar, AvatarGroup } from '@ifhover/leaf-ui';

export function AvatarBasic() {
  return (
    <AvatarGroup aria-label="Team members">
      {['Ada', 'Ben', 'Cara', 'Dan', 'Eva'].map((name) => (
        <Avatar key={name} alt={name}>
          {name.slice(0, 1)}
        </Avatar>
      ))}
    </AvatarGroup>
  );
}

Text avatar colors distinguish members; they do not indicate status.

Examples

Sizes

Use AvatarGroup.size to set the size of avatars in the group.

Small
Medium
Large
sizes.tsx
import { Avatar, AvatarGroup, Flex, Grid, Text } from '@ifhover/leaf-ui';
import { Fragment } from 'react';

const sizes = [
  { value: 'sm', label: 'Small' },
  { value: 'md', label: 'Medium' },
  { value: 'lg', label: 'Large' },
] as const;

export function AvatarSizes() {
  return (
    <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
      {sizes.map(({ value, label }) => (
        <Fragment key={value}>
          <Text tone="muted">{label}</Text>
          <Flex align="center" wrap>
            <AvatarGroup size={value} aria-label={`${label} team member avatars`}>
              {['Ada', 'Ben', 'Cara'].map((name) => (
                <Avatar key={name} alt={name}>
                  {name.slice(0, 1)}
                </Avatar>
              ))}
            </AvatarGroup>
          </Flex>
        </Fragment>
      ))}
    </Grid>
  );
}

Image avatars

Provide the member's name through alt, including when only initials are visible.

image.tsx
import { Avatar } from '@ifhover/leaf-ui';

const portrait = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(
  '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><title>Alex avatar illustration</title><rect width="100" height="100" fill="#e8efe8"/><path d="M8 100c2-27 17-42 42-42s40 15 42 42" fill="#32744d"/><path d="M36 62h28l-4 14-10 7-10-7z" fill="#e5af85"/><ellipse cx="50" cy="40" rx="22" ry="27" fill="#edc3a0"/><path d="M27 44c-8-30 8-38 23-38 23 0 30 22 23 41l-6-16-5-9c-9 10-20 14-31 14z" fill="#2e3c31"/><path d="M43 54q7 5 14 0" fill="none" stroke="#b1775a" stroke-width="2" stroke-linecap="round"/></svg>',
)}`;

export function AvatarImage() {
  return <Avatar src={portrait} alt="Alex" />;
}

Fallbacks and defaults

Failed images fall back to children, icon or the default icon. Changing the image source retries loading.

Text fallback
Default icon
fallback.tsx
import { Avatar, Flex, Grid, Text } from '@ifhover/leaf-ui';

export function AvatarFallback() {
  return (
    <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
      <Text tone="muted">Text fallback</Text>
      <Flex align="center" wrap>
        <Avatar src="data:image/png;base64,broken" alt="Alex">
          AL
        </Avatar>
      </Flex>
      <Text tone="muted">Default icon</Text>
      <Flex align="center" wrap>
        <Avatar alt="Guest" />
      </Flex>
    </Grid>
  );
}

Avatar group overflow

Set maxCount to limit visible members, then use +N to view the remaining members.

extensions.tsx
import { Avatar, AvatarGroup } from '@ifhover/leaf-ui';

export function ExtensionDemo() {
  return (
    <AvatarGroup maxCount={3} aria-label="Team members">
      {['Ada', 'Ben', 'Cara', 'Dan', 'Eva'].map((name) => (
        <Avatar key={name} alt={name}>
          {name.slice(0, 1)}
        </Avatar>
      ))}
    </AvatarGroup>
  );
}

Shapes

Use Avatar.shape to choose circular or square avatars.

Circle
Square
shapes.tsx
import { Avatar, Flex, Grid, Text } from '@ifhover/leaf-ui';

export function AvatarShapes() {
  return (
    <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
      <Text tone="muted">Circle</Text>
      <Flex align="center" wrap>
        <Avatar shape="circle" alt="Leaf">
          LF
        </Avatar>
      </Flex>
      <Text tone="muted">Square</Text>
      <Flex align="center" wrap>
        <Avatar shape="square" alt="Leaf">
          LF
        </Avatar>
      </Flex>
    </Grid>
  );
}

API

AvatarGroup API

Props for displaying member avatars as a group with overflow counts.

AvatarGroupProps API

PropertyTypeDefaultDescription
maxCountnumberInfinityMaximum visible avatars; the rest collapse into +N.
sizeAvatarProps['size']—Avatar size preset; a number is treated as pixels.
shapeAvatarProps['shape']—Crop shape
maxContent(hiddenCount: number) => ReactNode—Custom overflow count content

Avatar API

Props for an individual member avatar within a group.

PropertyTypeDefaultDescription
srcstring—Avatar image URL.
srcSetstring—Responsive image candidates.
imagePropsOmit<ImgHTMLAttributes<HTMLImageElement>, 'src' | 'srcSet' | 'alt' | 'onError'>—Image attributes such as loading, sizes, crossOrigin and objectFit styles
altstringText or localized defaultAccessible name
size'sm' | 'md' | 'lg' | number'md'Preset size or pixel value
shape'circle' | 'square''circle'Shape
iconReactNode—Icon displayed without an image.
onError() => void—Image loading error callback
childrenReactNode—Text or content displayed without an image.