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

# Avatar

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

## Anatomy

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

## Usage

Use Avatar where a person or resource needs a compact identity cue. Supply a meaningful `alt` for
identity images. Stack several people with [AvatarGroup](https://moraine.subf.dev/components/avatar-group.md).

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

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

### Image fallbacks

The fallback shows while the image is loading, missing, or failed. `text` sets the fallback text,
typically initials. When `text` is blank or omitted, the fallback shows up to two initials taken from
`alt`. `icon` is an icon name that replaces the text, for a generic placeholder. Avatar renders the
real `<img src>` during server rendering and uses native load and error events to switch between
image and fallback. `size` accepts `sm`, `md` (default), or `lg`.

```tsx
<Avatar src="/alex.png" alt="Alex Rivera" text="AR" />
<Avatar alt="Guest" icon="i-lucide:user" />
```

### Loading status

The image status is `loading`, `loaded`, or `error`. An empty or missing `src` is `error`. Use
`onStatusChange` when surrounding UI must react to a source change. It fires after mount with the
initial status and on every change, and never on the server. Pair it with a status label owned by the
page.

```tsx
<Avatar src={src()} alt="Alex" onStatusChange={setStatus} />
```

### Badge

`badge` accepts an icon name. `badgePosition` places it in a corner: `top-left`, `top-right`,
`bottom-left`, or `bottom-right` (default).

```tsx
<Avatar alt="Alex" text="A" badge="i-lucide:check" badgePosition="bottom-right" />
```

## Examples

### Recover a teammate when the photo is missing

Keep `alt` and initials so the row still identifies the person if `src` fails.

```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>
  )
}
```

### Track profile image load status

Drive nearby copy from `onStatusChange` when the page needs to know whether the photo loaded.

```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' ? 'soft' : 'outline'}>Status: {status()}</Badge>
    </div>
  )
}
```

### Fall back after a broken photo URL

Set `icon` as a placeholder and read the `error` status when the stored URL 404s.

```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}
        icon="i-lucide-user"
      />
      <p class="text-sm text-muted-foreground">Image status: {status()}</p>
    </div>
  )
}
```

### Mark verified and on-call teammates

Use `badge` for a status glyph. Place it where it will not cover the face.

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

export function BadgePositions() {
  return (
    <div class="flex flex-wrap gap-4 items-center">
      <Avatar alt="Sarah Connor" text="SC" badge="i-lucide:check" badgePosition="bottom-right" />
      <Avatar
        alt="On-call engineer"
        text="OC"
        badge="i-lucide:circle-alert"
        badgePosition="top-right"
      />
    </div>
  )
}
```

## API Reference

### 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 | — | Alt text of the image and accessible name of the fallback. When `text` is not set, the fallback<br>shows up to two initials taken from the first letters of the first words of `alt`. |
| badge | IconT.Name \| undefined | — | Name of an icon rendered in a small badge anchored to a corner of the avatar (see<br>`badgePosition`). Nothing is rendered when omitted. |
| badgePosition | 'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right' \| undefined | 'bottom-right' | Position of the badge relative to the avatar. |
| icon | IconT.Name \| undefined | — | Name of an icon shown in the fallback in place of `text` or initials while the image is unavailable. |
| onStatusChange | ((status: Status) => void) \| undefined | — | Called whenever the image status changes, including once after mount with the initial status<br>(`loading` when `src` is set, otherwise `error`). The status is `loaded` once the image has<br>loaded and `error` when it fails or `src` is empty. It is not called on the server. |
| size | 'sm' \| 'md' \| 'lg' \| undefined | 'md' | Visual size of the component. |
| src | string \| undefined | — | URL of the avatar image. Surrounding whitespace is trimmed. When empty or missing the status is<br>`error` and the fallback is shown; changing it restarts loading. |
| text | string \| undefined | — | Text shown in the fallback while the image is loading, failed, or missing, typically initials.<br>It is trimmed, and when blank the initials of `alt` are used instead. Ignored when `icon` is set. |
| 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. |

**`onStatusChange` example**

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

<Avatar
  src="/alex.png"
  alt="Alex Rivera"
  onStatusChange={(status) => console.log(status)}
/>
```
