# Avatar

A visual representation of a user or entity.

## Installation

Start from a Svelte 5 application, then install the component package, shared theme, and Bits UI peer:

```bash
pnpm add coss-svelte @coss-svelte/theme bits-ui
```

Import `@coss-svelte/theme/style-coss.css` after Tailwind from the application's global stylesheet.

## Usage

```svelte
<script lang="ts">
import { Avatar, AvatarFallback, AvatarImage } from "coss-svelte";
</script>

<Avatar>
	<AvatarImage
		alt="Luke Tracy"
		src="https://images.unsplash.com/photo-1543610892-0b1f7e6d8ac1?w=128&h=128&dpr=2&q=80"
	/>
	<AvatarFallback>LT</AvatarFallback>
</Avatar>

```

## Anatomy

- `Avatar`
- `AvatarFallback`
- `AvatarImage`

## API Reference

### Avatar

A visual representation of a user or entity.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | `string` | `""` | Image source for the avatar. |
| `alt` | `string` | - | Accessible text for the avatar image. |
| `fallback` | `string` | `""` | Text shown when the avatar image is unavailable. |

**Composition and refs**

- `children: Snippet<[]>`
- `bind:ref: HTMLElement \| null`

Inherits from [Bits UI Avatar.Root](https://bits-ui.com/docs/components/avatar#root).

### AvatarFallback

Renders fallback content when primary media is unavailable.

**Composition and refs**

- `children: Snippet<[]>`
- `bind:ref: HTMLElement \| null`

Inherits from [Bits UI Avatar.Fallback](https://bits-ui.com/docs/components/avatar#fallback).

### AvatarImage

Renders the primary image for the parent component.

**Composition and refs**

- `children: Snippet<[]>`
- `bind:ref: HTMLElement \| null`

Inherits from [Bits UI Avatar.Image](https://bits-ui.com/docs/components/avatar#image).

## Implementation Details

| Field | Value |
| --- | --- |
| Status | Stable |
| Foundation | bits |
| Category | Content & Display |
| Particles | 14 |

## Status

Stable for the current coss-svelte surface.

## Agent Notes

- Import Svelte exports directly from `coss-svelte`.
- This is Svelte 5 code: use `class`, lowercase event properties, runes, snippets, and documented `bind:*` contracts. Do not emit JSX, React hooks, `className`, `asChild`, or Base UI imports.
- Prefer this route's example and generated API table over React COSS snippets; COSS React particles are design references only.
- The copy-and-own registry is a preview. Inspect `/r/avatar.json` for the complete local file and dependency closure.
- Avatar is stable in the current source catalog.