---
title: Avatar
description: A circular user image with an initials or icon fallback.
---
import Source from './_generated/avatar.mdx';

A circular user image with a graceful fallback. While the image is missing or fails to load, the avatar shows `initials` (or a projected icon), then swaps to the image once it loads. Sizes are `sm` / `md` / `lg`. A `tcn-avatar-group` wrapper overlaps its members and rings each one — the styling differs only subtly per platform (the ring tone) and is carried by the cascade.

<DemoFrame component="avatar" />

## Installation

```bash
npx touchcn add avatar
```

## Usage

<CodeGroup>

```html Angular
<tcn-avatar size="md" src="/avatar.jpg" alt="Avery" initials="AV" />

<tcn-avatar-group>
  <tcn-avatar src="/one.jpg" alt="One" initials="1" />
  <tcn-avatar src="/two.jpg" alt="Two" initials="2" />
  <tcn-avatar initials="+5" />
</tcn-avatar-group>
```

```tsx React
import { TcnAvatar, TcnAvatarGroup } from '@/components/ui/avatar';

<TcnAvatar size="md" src="/avatar.jpg" alt="Avery" initials="AV" />

<TcnAvatarGroup>
  <TcnAvatar src="/one.jpg" alt="One" initials="1" />
  <TcnAvatar src="/two.jpg" alt="Two" initials="2" />
  <TcnAvatar initials="+5" />
</TcnAvatarGroup>
```

```vue Vue
<script setup lang="ts">
import { TcnAvatar, TcnAvatarGroup } from '@/components/ui/avatar';
</script>

<template>
  <TcnAvatar size="md" src="/avatar.jpg" alt="Avery" initials="AV" />

  <TcnAvatarGroup>
    <TcnAvatar src="/one.jpg" alt="One" initials="1" />
    <TcnAvatar src="/two.jpg" alt="Two" initials="2" />
    <TcnAvatar initials="+5" />
  </TcnAvatarGroup>
</template>
```

</CodeGroup>

The only behaviour is a boolean load/error flag, so it stays in the copied component — no engine plumbing. Projected content (Angular `ng-content`, React `children`) renders as the fallback, so an icon can stand in for missing initials.

## Props

### Avatar

| Prop       | Type                   | Default | Description                                    |
| ---------- | ---------------------- | ------- | ---------------------------------------------- |
| `src`      | `string`               | `''`    | Image URL; falls back on error or while empty. |
| `alt`      | `string`               | `''`    | Alt text for the image.                        |
| `initials` | `string`               | `''`    | Fallback initials shown when there's no image. |
| `size`     | `'sm' \| 'md' \| 'lg'` | `'md'`  | Avatar diameter.                               |

<Source />