---
title: Avatar
description: Show a person or resource image with a fallback while the image loads.
package: moraine
version: 0.6.0
repository: https://github.com/subframe7536/moraine
---

# Avatar

> Show a person or resource image with a fallback while the image loads.

Use Avatar where a person or resource needs a compact identity cue. Supply a meaningful `alt` for identity images; the fallback remains visible until the image loads.

## Basic usage

```tsx
import { Avatar } from 'moraine'

export function Example() {
  return <Avatar src="/avatar.png" alt="Alex" fallback="A" />
}
```

## Anatomy

```text
Avatar [component; slot=root; <span>]
├── image [slot]
├── fallback [slot]
│   └── fallbackContent [slot]
└── badge [slot]
```

## Usage

### Image fallbacks

Provide useful `alt` text for an image that conveys identity. When the image cannot load, the component can fall back to supplied text or initials; the application remains responsible for choosing an unambiguous accessible name.

`Avatar` renders the real `<img src>` during server rendering and uses native image load and error events to switch between image and fallback. Status is `loading`, `loaded`, or `error`.

```tsx
import { Avatar } from 'moraine'

export function FallbackUsage() {
  return (
    <div class="flex gap-4 items-center">
      <Avatar
        src="https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=128&fit=crop&q=80"
        alt="Sarah Connor"
        text="SC"
      />
      <Avatar src="/invalid-image-path.jpg" alt="Alex Rivera" text="AR" />
      <Avatar alt="Guest User" />
    </div>
  )
}
```

### Loading status

Use image loading and error callbacks when surrounding UI needs to respond to a changed source status.

```tsx
import { Avatar, Badge } from 'moraine'
import type { AvatarT } from 'moraine'
import { createSignal } from 'solid-js'

export function LoadingUsage() {
  const [status, setStatus] = createSignal<AvatarT.Status>('loading')

  return (
    <div class="flex gap-4 items-center">
      <Avatar
        src="https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=128&fit=crop&q=80"
        alt="Sarah Connor"
        onStatusChange={setStatus}
      />
      <Badge variant={status() === 'loaded' ? 'subtle' : 'outline'}>Status: {status()}</Badge>
    </div>
  )
}
```

## Examples

### Fallback modes

```tsx
import { Avatar } from 'moraine'

export function FallbackModes() {
  return (
    <div class="flex flex-wrap gap-3 items-center">
      <Avatar text="MR" />
      <Avatar alt="Moraine Team" />
      <Avatar fallback="i-lucide-user" />
    </div>
  )
}
```

### Loading status

```tsx
import { Avatar } from 'moraine'
import type { AvatarT } from 'moraine'
import { createSignal } from 'solid-js'

export function StatusChange() {
  const [status, setStatus] = createSignal<AvatarT.Status>('loading')

  return (
    <div class="flex gap-3 items-center">
      <Avatar
        src="/avatar-does-not-exist.png"
        alt="Taylor Kim"
        onStatusChange={setStatus}
        fallback="i-lucide-user"
      />
      <p class="text-sm text-muted-foreground">Image status: {status()}</p>
    </div>
  )
}
```

### Badge and group composition

```tsx
import { Avatar } from 'moraine'

export function BadgePositions() {
  return (
    <div class="flex flex-wrap gap-3 items-center">
      <Avatar text="A" badge="i-lucide-check" badgePosition="top-left" />
      <Avatar text="B" badge="i-lucide-check" badgePosition="top-right" />
      <Avatar text="C" badge="i-lucide-check" badgePosition="bottom-left" />
      <Avatar text="D" badge="i-lucide-check" badgePosition="bottom-right" />
    </div>
  )
}
```

## Attributes

| Attributes | Slot | Description |
| --- | --- | --- |
| `data-status` | `avatar`, `avatar-image`, `avatar-fallback` | Stores async loading, loaded, or error status. |

## Props

Props for the Avatar component.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| alt | string \| undefined | — | Accessible alt text for the avatar. |
| badge | IconT.Name \| undefined | — | Icon name for the badge. |
| badgePosition | NonNullable<Variant['badgePosition']> \| undefined | 'bottom-right' | Position of the badge. |
| fallback | IconT.Name \| undefined | — | Icon name to show as fallback. |
| onStatusChange | ((status: Status) => void) \| undefined | — | Callback when the loading status of the avatar changes. |
| size | 'sm' \| 'md' \| 'lg' \| undefined | 'md' | Visual size of the component. |
| src | string \| undefined | — | Source URL for the avatar image. |
| text | string \| undefined | — | Initial text to show if image fails or is missing. |
| class | SlotClassValue \| undefined | — | Class applied to the component root or trigger element. |
| classes | Classes \| undefined | — | Family slot class defaults for this instance. |
| style | SlotStyleValue \| undefined | — | Style applied to the component root or trigger element. |
| styles | Styles \| undefined | — | Family slot style defaults for this instance. |