Skip to main content

Avatar

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

SC
Props
Slots

Anatomy#

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.

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.

<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.

<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).

<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.

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.

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.

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.

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
data-status
Slot: avataravatar-imageavatar-fallback
Description: Stores async loading, loaded, or error status.

Props#

Props for the Avatar component. Renders a <span> element by default.

Prop