---
title: Avatar
description: "An image element with a fallback for representing the user."
---

```tsx
import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar';

export default function AvatarDemo() {
  return (
    <Avatar>
      <AvatarImage src="https://github.com/madeui.png" alt="@madeui" />
      <AvatarFallback>MD</AvatarFallback>
    </Avatar>
  );
}
```

## Install

```bash
npx shadcn@latest add @madeui/avatar
```

## Usage

```tsx
import {
  Avatar,
  AvatarBadge,
  AvatarFallback,
  AvatarGroup,
  AvatarGroupCount,
  AvatarImage,
} from '@/components/ui/avatar';
```

## Composition

```tsx
<Avatar>
  <AvatarImage />
  <AvatarFallback />
  <AvatarBadge />
</Avatar>
```

## Sizes

```tsx
import * as stylex from '@stylexjs/stylex';

import { space } from '@/lib/constants.stylex';

import { Avatar, AvatarFallback } from '@/components/ui/avatar';

export default function AvatarSizes() {
  return (
    <div {...stylex.props(styles.row)}>
      <Avatar size="sm">
        <AvatarFallback>SM</AvatarFallback>
      </Avatar>
      <Avatar size="md">
        <AvatarFallback>MD</AvatarFallback>
      </Avatar>
      <Avatar size="lg">
        <AvatarFallback>LG</AvatarFallback>
      </Avatar>
    </div>
  );
}

const styles = stylex.create({
  row: {
    alignItems: 'center',
    display: 'flex',
    flexWrap: 'wrap',
    gap: space.s2,
  },
});
```

## Fallback

The fallback renders while the image loads — or when it fails. Always provide one.

```tsx
import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar';

// The fallback renders while the image loads — or when it fails.
export default function AvatarFallbackDemo() {
  return (
    <Avatar>
      <AvatarImage src="https://example.com/broken.png" alt="Broken" />
      <AvatarFallback>UI</AvatarFallback>
    </Avatar>
  );
}
```

## Badge

`AvatarBadge` anchors a status indicator to the bottom-right corner. Pass a small icon as children for something other than a plain dot.

```tsx
import * as stylex from '@stylexjs/stylex';

import { Avatar, AvatarBadge, AvatarFallback, AvatarImage } from '@/components/ui/avatar';
import { space } from '@/lib/constants.stylex';

export default function AvatarBadgeDemo() {
  return (
    <div {...stylex.props(styles.row)}>
      <Avatar>
        <AvatarImage src="https://github.com/madeui.png" alt="@madeui" />
        <AvatarFallback>MD</AvatarFallback>
        <AvatarBadge />
      </Avatar>
      <Avatar>
        <AvatarImage src="https://github.com/github.png" alt="@github" />
        <AvatarFallback>GH</AvatarFallback>
        <AvatarBadge>
          <svg width="8" height="8" viewBox={`0 0 8 8`} fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden>
            <path d={`M1.5 4.2 3.2 5.9 6.5 2.1`} />
          </svg>
        </AvatarBadge>
      </Avatar>
    </div>
  );
}

const styles = stylex.create({
  row: {
    alignItems: 'center',
    display: 'flex',
    gap: space.s6,
  },
});
```

## Group

`AvatarGroup` overlaps its children with a `colors.background` ring separating each one.

```tsx
import { Avatar, AvatarFallback, AvatarGroup, AvatarImage } from '@/components/ui/avatar';

export default function AvatarGroupDemo() {
  return (
    <AvatarGroup>
      <Avatar>
        <AvatarImage src="https://github.com/madeui.png" alt="@madeui" />
        <AvatarFallback>MD</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarImage src="https://github.com/github.png" alt="@github" />
        <AvatarFallback>GH</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarImage src="https://github.com/vercel.png" alt="@vercel" />
        <AvatarFallback>VC</AvatarFallback>
      </Avatar>
    </AvatarGroup>
  );
}
```

## Group count

Add an `AvatarGroupCount` as the last child to show a "+N" overflow indicator.

```tsx
import {
  Avatar,
  AvatarFallback,
  AvatarGroup,
  AvatarGroupCount,
  AvatarImage,
} from '@/components/ui/avatar';

export default function AvatarGroupCountDemo() {
  return (
    <AvatarGroup>
      <Avatar>
        <AvatarImage src="https://github.com/madeui.png" alt="@madeui" />
        <AvatarFallback>MD</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarImage src="https://github.com/github.png" alt="@github" />
        <AvatarFallback>GH</AvatarFallback>
      </Avatar>
      <AvatarGroupCount>+3</AvatarGroupCount>
    </AvatarGroup>
  );
}
```

## API reference

Built on [Base UI Avatar](https://base-ui.com/react/components/avatar). The tables below cover the props this library adds or changes — every other prop is forwarded to the underlying Base UI part; see the [Base UI Avatar API reference](https://base-ui.com/react/components/avatar#api-reference) for the full list.

### Avatar

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` |  |
| `style` | `StyleXStyles` | — | StyleX styles merged last — always win over the component's own styles. |

### AvatarGroupCount

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Matches the size of the avatars in the group. |
| `style` | `StyleXStyles` | — | StyleX styles merged last — always win over the component's own styles. |

### Styling

`AvatarImage`, `AvatarFallback`, `AvatarBadge`, `AvatarGroup` accept `style` (`StyleXStyles`, merged last so caller overrides always win) plus all native props of the element they render.