@fictjs/avatar

Avatar primitives for Fict, modeled after @radix-ui/react-avatar. An image element with a graceful fallback while the image loads or when it fails.

Part of ui-primitives, a port of Radix Primitives to Fict.

Installation

pnpm add @fictjs/avatar fict

Usage

/** @jsxImportSource fict */
import * as Avatar from '@fictjs/avatar'

export function Example() {
  return (
    <Avatar.Root>
      <Avatar.Image src="/user.jpg" alt="Jane Doe" />
      <Avatar.Fallback delayMs={600}>JD</Avatar.Fallback>
    </Avatar.Root>
  )
}

Anatomy

• Avatar.Root (Root) — wraps the image and fallback.
• Avatar.Image (Image) — src, alt, onLoadingStatusChange. Only renders once the image has loaded.
• Avatar.Fallback (Fallback) — delayMs to avoid a flash for fast connections. Rendered until the image loads.

The loading lifecycle is exposed through the ImageLoadingStatus type ("idle" | "loading" | "loaded" | "error").

Exports

• Components: Avatar (Root), AvatarImage (Image), AvatarFallback (Fallback), createAvatarScope.
• Types: AvatarProps, AvatarImageProps, AvatarFallbackProps, ImageLoadingStatus.

Documentation

The API mirrors Radix, so the upstream Radix Avatar docs apply. See the ui-primitives overview and the architecture guide for the Fict-specific reactivity model.

License

MIT © Fict contributors.