---
title: "Avatar"
description: "A circular identity image with initials and an optional presence dot."
category: "Display & Misc"
slug: avatar
url: /components/avatar
since: "0.2.0"
status: "stable"
---

# Avatar

A circular identity image with initials and an optional presence dot.

## Import

```svelte
import { Avatar } from '@elluzion/iv-ui';
```

## Preview

`xs`, `sm`, `md`, and `lg` steps.

```svelte
<script lang="ts">
	import { Avatar } from '@elluzion/iv-ui';
</script>

<div class="row">
	<Avatar size="xs" fallback="AL" alt="Ada Lovelace" />
	<Avatar size="sm" fallback="GH" alt="Grace Hopper" />
	<Avatar fallback="AT" alt="Alan Turing" />
	<Avatar size="lg" fallback="KJ" alt="Katherine Johnson" />
</div>

<style>
	.row {
		display: flex;
		align-items: center;
		gap: var(--iv_spacing-md);
	}
</style>
```

## Usage

- `fallback` initials show when `src` is missing or fails to load.
- Pass an empty `alt` for decorative avatars; otherwise `alt` names the person.
- `status` adds a presence dot: neutral, success, error, info, or accent.

## Examples

### Fallback

Initials are used when there is no image or the image fails.

```svelte
<script lang="ts">
	import { Avatar } from '@elluzion/iv-ui';
</script>

<div class="row">
	<Avatar fallback="AL" alt="Ada Lovelace" />
	<Avatar src="data:image/png;base64,invalid" fallback="GH" alt="Grace Hopper" />
	<Avatar src="data:image/png;base64,invalid" fallback="AT" alt="Alan Turing" />
</div>

<style>
	.row {
		display: flex;
		align-items: center;
		gap: var(--iv_spacing-md);
	}
</style>
```

### Status

A presence dot in the corner, with every status treatment.

```svelte
<script lang="ts">
	import { Avatar } from '@elluzion/iv-ui';
</script>

<div class="row">
	<Avatar fallback="AL" alt="Ada Lovelace" status="success" />
	<Avatar fallback="GH" alt="Grace Hopper" status="error" />
	<Avatar fallback="AT" alt="Alan Turing" status="info" />
	<Avatar fallback="KJ" alt="Katherine Johnson" status="accent" />
	<Avatar fallback="MH" alt="Margaret Hamilton" status="neutral" />
</div>

<style>
	.row {
		display: flex;
		align-items: center;
		gap: var(--iv_spacing-md);
	}
</style>
```

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | `string` | `''` | Image source. Falls back to `fallback` initials when missing or broken. |
| `alt` | `string` | `''` | Accessible name for the image. Use an empty string for decorative avatars. |
| `size` | `AvatarSize` | `'md'` | Control size. |
| `fallback` | `string` | `''` | Initials shown when there is no image. |
| `status` | `AvatarStatus` | — | Presence dot treatment. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |

`class`, `id`, `style`, `aria-*`, and `data-*` are forwarded through rest props.

### Snippets

| Snippet | Type | Description |
| --- | --- | --- |
| `children` | `Snippet` | Custom avatar content replacing the image. |

### Types

#### `AvatarSize`

Avatar diameter steps.

```ts
type AvatarSize = 'xs' | 'sm' | 'md' | 'lg';
```

#### `AvatarStatus`

Presence dot treatments.

```ts
type AvatarStatus = 'neutral' | 'success' | 'error' | 'info' | 'accent';
```

### Tokens used

`--iv_accent` · `--iv_avatar-lg` · `--iv_avatar-md` · `--iv_avatar-sm` · `--iv_avatar-xs` · `--iv_border` · `--iv_error` · `--iv_foreground-dim` · `--iv_info` · `--iv_leading-none` · `--iv_radius-pill` · `--iv_spacing-sm` · `--iv_success` · `--iv_surface` · `--iv_surface-elevated` · `--iv_text-base` · `--iv_text-body-sm` · `--iv_text-sm` · `--iv_text-xs` · `--iv_weight-medium`

See the [token reference](/foundations/tokens.md) for values.

### CSS hooks

`.iv-accent` · `.iv-avatar` · `.iv-avatar-fallback` · `.iv-avatar-img` · `.iv-avatar-overlay` · `.iv-avatar-status` · `.iv-error` · `.iv-info` · `.iv-lg` · `.iv-neutral` · `.iv-sm` · `.iv-success` · `.iv-xs`

## Accessibility

- When the image is present, `alt` is its accessible name.
- The initials fallback gets `role="img"` and the same name when `alt` is set.
- An empty `alt` makes the avatar decorative; use it when the name is already next to the avatar.

## Related

- [Badge](/components/badge.md)
- [Card](/components/card.md)
- [Shortcut](/components/shortcut.md)
- [EmptyState](/components/empty-state.md)