> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/en/components/avatar.html

> 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.

# 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`.


ABCDE

basic.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/avatar/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>
  );
}
```

Expand code

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

ABC

Medium

ABC

Large

ABC

sizes.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/avatar/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>
  );
}
```

Expand code

### Image avatars

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


![](data:image/svg+xml;charset=utf-8,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%20100%20100%22%3E%3Ctitle%3EAlex%20avatar%20illustration%3C%2Ftitle%3E%3Crect%20width%3D%22100%22%20height%3D%22100%22%20fill%3D%22%23e8efe8%22%2F%3E%3Cpath%20d%3D%22M8%20100c2-27%2017-42%2042-42s40%2015%2042%2042%22%20fill%3D%22%2332744d%22%2F%3E%3Cpath%20d%3D%22M36%2062h28l-4%2014-10%207-10-7z%22%20fill%3D%22%23e5af85%22%2F%3E%3Cellipse%20cx%3D%2250%22%20cy%3D%2240%22%20rx%3D%2222%22%20ry%3D%2227%22%20fill%3D%22%23edc3a0%22%2F%3E%3Cpath%20d%3D%22M27%2044c-8-30%208-38%2023-38%2023%200%2030%2022%2023%2041l-6-16-5-9c-9%2010-20%2014-31%2014z%22%20fill%3D%22%232e3c31%22%2F%3E%3Cpath%20d%3D%22M43%2054q7%205%2014%200%22%20fill%3D%22none%22%20stroke%3D%22%23b1775a%22%20stroke-width%3D%222%22%20stroke-linecap%3D%22round%22%2F%3E%3C%2Fsvg%3E)

image.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/avatar/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" />;
}
```

Expand code

### Fallbacks and defaults

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


Text fallback

AL![](data:image/png;base64,broken)

Default icon

fallback.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/avatar/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>
  );
}
```

Expand code

### Avatar group overflow

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


ABC+2

extensions.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/avatar/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>
  );
}
```

Expand code

### Shapes

Use `Avatar.shape` to choose circular or square avatars.


Circle

LF

Square

LF

shapes.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/avatar/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>
  );
}
```

Expand code


## API

### AvatarGroup API

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

#### AvatarGroupProps API

| Property     | Type                                    | Default    | Description                                         |
| ------------ | --------------------------------------- | ---------- | --------------------------------------------------- |
| `maxCount`   | `number`                                | `Infinity` | Maximum visible avatars; the rest collapse into +N. |
| `size`       | [`AvatarProps`](#avatar-api)`['size']`  | —          | Avatar size preset; a number is treated as pixels.  |
| `shape`      | [`AvatarProps`](#avatar-api)`['shape']` | —          | Crop shape                                          |
| `maxContent` | `(hiddenCount: number) => ReactNode`    | —          | Custom overflow count content                       |

### Avatar API

Props for an individual member avatar within a group.

| Property     | Type                                                                                 | Default                   | Description                                                               |
| ------------ | ------------------------------------------------------------------------------------ | ------------------------- | ------------------------------------------------------------------------- |
| `src`        | `string`                                                                             | —                         | Avatar image URL.                                                         |
| `srcSet`     | `string`                                                                             | —                         | Responsive image candidates.                                              |
| `imageProps` | `Omit<ImgHTMLAttributes<HTMLImageElement>, 'src' \| 'srcSet' \| 'alt' \| 'onError'>` | —                         | Image attributes such as loading, sizes, crossOrigin and objectFit styles |
| `alt`        | `string`                                                                             | Text or localized default | Accessible name                                                           |
| `size`       | `'sm' \| 'md' \| 'lg' \| number`                                                     | `'md'`                    | Preset size or pixel value                                                |
| `shape`      | `'circle' \| 'square'`                                                               | `'circle'`                | Shape                                                                     |
| `icon`       | `ReactNode`                                                                          | —                         | Icon displayed without an image.                                          |
| `onError`    | `() => void`                                                                         | —                         | Image loading error callback                                              |
| `children`   | `ReactNode`                                                                          | —                         | Text or content displayed without an image.                               |
