elementsavatar

Avatar

Circular user or entity avatar with fallback initials and an optional indicator.

Import#

import { Avatar } from 'moraine'

Slot Structure#

Avatar renders a single image/fallback frame. Use AvatarGroup for grouped avatars with an overflow counter.

Single avatar#

root
├── image
├── fallback
│   └── fallbackIcon (Icon, optional)
└── badge (optional)

Examples#

Single Avatar#

Fallback first, then image crossfades in after preload.

1
function SingleAvatar() {
2
  const IMAGE_A = createSvgDataUrl('A', '#3f3f46')
3

4
  const IMAGE_B = createSvgDataUrl('B', '#18181b')
5

6
  const [source, setSource] = createSignal(IMAGE_A)
7

8
  function createSvgDataUrl(label: string, backgroundColor: string): string {
9
    const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><rect width="64" height="64" fill="${backgroundColor}"/><text x="32" y="38" text-anchor="middle" fill="white" font-family="sans-serif" font-size="24">${label}</text></svg>`
10
    return `data:image/svg+xml;utf8,${encodeURIComponent(svg)}`
11
  }
12

13
  return (
14
    <div class="flex gap-4 items-center">
15
      <Avatar
16
        src={source()}
17
        alt="Moraine"
18
        classes={{
19
          root: 'ring-ring',
20
        }}
21
      />
22

23
      <Button
24
        variant="outline"
25
        onClick={() => {
26
          setSource((current) => (current === IMAGE_A ? IMAGE_B : IMAGE_A))
27
        }}
28
      >
29
        Swap Source
30
      </Button>
31
    </div>
32
  )
33
}

Sizes#

Scale single avatars from xs to xl.

1
function Sizes() {
2
  const SIZES: AvatarSize[] = ['xs', 'sm', 'md', 'lg', 'xl']
3

4
  return (
5
    <div class="flex flex-wrap gap-4 items-end">
6
      <For each={SIZES}>
7
        {(size) => (
8
          <div class="flex flex-col gap-2 items-center">
9
            <Avatar size={size} text="MR" />
10
            <span class="text-xs text-muted-foreground font-mono">{size}</span>
11
          </div>
12
        )}
13
      </For>
14
    </div>
15
  )
16
}

Fallback Modes#

Text, initials-from-alt and fallback icon.

1
function FallbackModes() {
2
  return (
3
    <div class="flex flex-wrap gap-3 items-center">
4
      <Avatar text="MR" />
5
      <Avatar alt="Moraine Team" />
6
      <Avatar fallback="i-lucide-user" />
7
    </div>
8
  )
9
}

Badge Positions#

Top/bottom + left/right corner badge.

1
function BadgePositions() {
2
  return (
3
    <div class="flex flex-wrap gap-3 items-center">
4
      <Avatar text="A" badge="i-lucide-check" badgePosition="top-left" />
5
      <Avatar text="B" badge="i-lucide-check" badgePosition="top-right" />
6
      <Avatar text="C" badge="i-lucide-check" badgePosition="bottom-left" />
7
      <Avatar text="D" badge="i-lucide-check" badgePosition="bottom-right" />
8
    </div>
9
  )
10
}

API Reference#

Attributes#

Slotroot0 attributes

Avatar frame that controls size, shape, image, fallback, and badge placement.

No attribute metadata for this slot.

Props#

Prop	Type	Default	Description
alt	`string \| undefined`	—	Accessible alt text for the avatar.
badge	`IconT.Name`	—	Icon name for the badge.
badgePosition	`"top-left" \| "top-right" \| "bottom-left" \| "bottom-right" \| undefined`	`bottom-right`	Position of the badge.
class	`ClassValue`	—	Class applied to the component root or trigger element.
classes	`AvatarT.Classes \| undefined`	—	—
fallback	`IconT.Name`	—	Icon name to show as fallback.
onStatusChange	`((status: AvatarStatus) => void) \| undefined`	—	Callback when the loading status of the avatar changes.
ref	`JSX.HTMLElementTags["span"] extends { ref?: infer Ref; } ? Ref : never \| undefined`	—	—
size	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined`	—	—
src	`string \| undefined`	—	Source URL for the avatar image.
style	`JSX.CSSProperties \| undefined`	—	—
styles	`AvatarT.Styles \| undefined`	—	—
text	`string \| undefined`	—	Initial text to show if image fails or is missing.
transition	`"none" \| "fast" \| "normal" \| "slow" \| undefined`	—	—

Items#

Prop	Type	Default	Description
alt	`string \| undefined`	—	Accessible alt text for the avatar.
badge	`IconT.Name`	—	Icon name for the badge.
badgePosition	`NonNullable<"top-left" \| "top-right" \| "bottom-left" \| "bottom-right" \| undefined> \| undefined`	`bottom-right`	Position of the badge.
fallback	`IconT.Name`	—	Icon name to show as fallback.
onStatusChange	`((status: AvatarStatus) => void) \| undefined`	—	Callback when the loading status of the avatar changes.
src	`string \| undefined`	—	Source URL for the avatar image.
text	`string \| undefined`	—	Initial text to show if image fails or is missing.