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

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/v/0.6.0/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/v/0.6.0/en/llms-full.txt.

# Avatar

Display an avatar for a user, team or object.

## Sizes and shapes


SmallLF

MediumLE

Large · SquareUI

Unread indicatorA

basic.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/avatar/basic.tsx"
import { Avatar, Badge, Flex, Text } from '@ifhover/leaf-ui';

export function AvatarBasic() {
  return (
    <Flex gap="md" align="center" wrap justify="center">
      <Flex direction="column" gap="sm" align="start">
        <Text>Small</Text>
        <Avatar size="sm">LF</Avatar>
      </Flex>
      <Flex direction="column" gap="sm" align="start">
        <Text>Medium</Text>
        <Avatar>LE</Avatar>
      </Flex>
      <Flex direction="column" gap="sm" align="start">
        <Text>Large · Square</Text>
        <Avatar size="lg" shape="square">
          UI
        </Avatar>
      </Flex>
      <Flex direction="column" gap="sm" align="start">
        <Text>Unread indicator</Text>
        <Badge dot>
          <Avatar alt="Unread messages">A</Avatar>
        </Badge>
      </Flex>
    </Flex>
  );
}
```

Expand code

## Image avatars


Circle image![](../../avatar-portrait.svg)

Square image![](../../avatar-portrait.svg)

image.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/avatar/image.tsx"
import { Avatar, Flex, Text } from '@ifhover/leaf-ui';

export function AvatarImage() {
  const image = '../../avatar-portrait.svg';
  return (
    <Flex gap="md" align="center" wrap justify="center">
      <Flex direction="column" gap="sm" align="start">
        <Text>Circle image</Text>
        <Avatar src={image} alt="Alex" size="lg" />
      </Flex>
      <Flex direction="column" gap="sm" align="start">
        <Text>Square image</Text>
        <Avatar src={image} alt="Alex" size={64} shape="square" imageProps={{ loading: 'lazy' }} />
      </Flex>
    </Flex>
  );
}
```

Expand code

## Fallbacks and defaults


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

Default icon

fallback.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/avatar/fallback.tsx"
import { Avatar, Flex, Text } from '@ifhover/leaf-ui';

export function AvatarFallback() {
  return (
    <Flex gap="md" align="center" wrap justify="center">
      <Flex direction="column" gap="sm" align="start">
        <Text>Text fallback</Text>
        <Avatar src="data:image/png;base64,broken" alt="Failed image">
          LF
        </Avatar>
      </Flex>
      <Flex direction="column" gap="sm" align="start">
        <Text>Default icon</Text>
        <Avatar alt="Guest" />
      </Flex>
    </Flex>
  );
}
```

Expand code

## Extended features


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}>
      {['Ada', 'Ben', 'Cara', 'Dan', 'Eva'].map((name) => (
        <Avatar key={name} alt={name}>
          {name.slice(0, 1)}
        </Avatar>
      ))}
    </AvatarGroup>
  );
}
```

Expand code

## Avatar API

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

## Types

Import these types to define props or prepare data.

```ts
import type { AvatarProps } from '@ifhover/leaf-ui';
```

## Usage notes

Failed images fall back to children, icon or the default avatar. Changing the source retries loading. Alt provides an accessible name without duplicate image announcements. Use imageProps.style to customize cropping.

## Extension types

```ts
import type { AvatarGroupProps } from '@ifhover/leaf-ui';
```

## AvatarGroupProps API

| Property     | Type                                 | Default    | Description                         |
| ------------ | ------------------------------------ | ---------- | ----------------------------------- |
| `maxCount`   | `number`                             | `Infinity` | Maximum selections or visible items |
| `size`       | `'sm' \| 'md' \| 'lg' \| number`     | —          | Size or spacing preset              |
| `shape`      | `'circle' \| 'square'`               | —          | Crop shape                          |
| `maxContent` | `(hiddenCount: number) => ReactNode` | —          | Custom overflow count content       |