Avatar

A user image with a fallback.

<script setup lang="ts">
import { Avatar } from '@shardsui/vue/avatar'
</script>

<template>
  <div class="flex gap-4">
    <Avatar.Root
      class="inline-flex size-10 items-center justify-center overflow-hidden rounded-full bg-gray-100 align-middle text-sm leading-none font-medium text-gray-900 select-none"
    >
      <Avatar.Image
        src="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg'><linearGradient id='g' x2='1' y2='1'><stop stop-color='%23e2e8f0'/><stop offset='.5' stop-color='%2394a3b8'/><stop offset='1' stop-color='%23334155'/></linearGradient><rect width='100%25' height='100%25' fill='url(%23g)'/></svg>"
        alt="Paul Rand"
        class="size-full object-cover"
      />
      <Avatar.Fallback :delay="300" class="flex size-full items-center justify-center">
        PR
      </Avatar.Fallback>
    </Avatar.Root>

    <Avatar.Root
      class="inline-flex size-10 items-center justify-center overflow-hidden rounded-full bg-gray-100 align-middle text-sm leading-none font-medium text-gray-900 select-none"
    >
      <Avatar.Image src="data:," alt="Milton Glaser" class="size-full object-cover" />
      <Avatar.Fallback :delay="300" class="flex size-full items-center justify-center">
        MG
      </Avatar.Fallback>
    </Avatar.Root>
  </div>
</template>

Anatomy

<script setup>
import { Avatar } from '@shardsui/vue/avatar'
</script>

<template>
  <Avatar.Root>
    <Avatar.Image />
    <Avatar.Fallback />
  </Avatar.Root>
</template>

API reference

Root

Groups the image and its fallback. Renders a <span> element.

Prop	Type	Default
`as`	`keyof HTMLElementTagNameMap`	`'span'`

`class`	`string`	—

`style`	`string`	—

`default`	`Slot<{ imageLoadingStatus }>`	—

Image

Renders an <img> element.

The component preloads the image — applying the same src, srcset, sizes, crossorigin and referrerpolicy — so the loading status is known from the first render. Those five are declared props rather than fallthrough attributes, so changing any of them restarts the preload. The <img> mounts only once the image has loaded, which is why it can be animated in with data-starting-style; see Animation.

Prop	Type	Default
`as`	`keyof HTMLElementTagNameMap`	`'img'`

`class`	`string`	—

`style`	`string`	—

`src`	`string`	—

`srcset`	`string`	—

`sizes`	`string`	—

`crossorigin`	`'anonymous' \| 'use-credentials' \| ''`	—

`referrerpolicy`	`ReferrerPolicy`	—

`alt`	`string`	—

`loadingStatusChange`	`(status: ImageLoadingStatus) => void`	—

Attribute	Description
`data-starting-style`	Present when the image is animating in.
`data-ending-style`	Present when the image is animating out.

Fallback

Rendered while the image is missing, still loading, or failed. Renders a <span> element.

Prop	Type	Default
`as`	`keyof HTMLElementTagNameMap`	`'span'`

`class`	`string`	—

`style`	`string`	—

`delay`	`number`	`0`

`default`	`Slot<{ imageLoadingStatus }>`	—

Additional types

ImageLoadingStatus

The status carried by loadingStatusChange, and passed to the default slot of Root and Fallback as imageLoadingStatus.

type ImageLoadingStatus = 'idle' | 'loading' | 'loaded' | 'error'