Avatar

Installation

$npx litefy@latest add avatar
$pnpm dlx litefy@latest add avatar
$yarn dlx litefy@latest add avatar
$bun --bun litefy@latest add avatar

Usage

Avatar component handling image loading, success, and failure states with skeleton and fallback.

"use client";
import { Avatar } from "@/ui";

export default function AvatarDemo() {
  return (
    <div className="flex gap-4 items-center">
      <Avatar src="https://picsum.photos/seed/av1/200/200" alt="user avatar" />

      <Avatar
        alt="broken avatar"
        skeleton={<div className="bg-neutral animate-pulse size-full" />}
        fallback={
          <div className="flex items-center justify-center  bg-neutral text-background size-full font-bold">
            US
          </div>
        }
      />
    </div>
  );
}

Custom

Compose AvatarRoot and AvatarImage directly. They carry the same default styles as the composite Avatar and can be freely assembled and overridden via className.

"use client";
import { AvatarRoot, AvatarImage } from "@/ui";

export default function AvatarAtomicDemo() {
  return (
    <AvatarRoot className="w-14 h-14 rounded-full bg-muted overflow-hidden">
      <AvatarImage
        src="https://picsum.photos/seed/av1/200/200"
        alt="user avatar"
        className="object-cover"
      />
    </AvatarRoot>
  );
}

API Reference

High-level Components

Ready-to-use composite components.

A self-managing avatar component that preloads the image and switches between skeleton, image, and fallback states.

Prop	Type	Default	Description
`src`	`string`	-	Image source URL, required
`skeleton`	`React.ReactNode`	-	Content shown while the image is loading
`fallback`	`React.ReactNode`	-	Content shown when the image fails to load
`className`	`ClassNameValue`	-	Custom classes, applied to the root container
`style`	`React.CSSProperties`	-	Inline styles, applied to the root container
`classNames`	`{ image?: ClassNameValue }`	-	Custom classes for the image
`styles`	`{ image?: React.CSSProperties }`	-	Inline styles for the image

Supports all native <img> attributes (such as alt); className and style apply to the root container.

Composable Components

AvatarRoot

The container element rendered as a square with default size-12, centered content and hidden overflow.

Prop	Type	Default	Description
`className`	`ClassNameValue`	-	Custom CSS class

Supports all native <div> attributes.

AvatarImage

The image element rendered with lazy loading and async decoding.

Prop	Type	Default	Description
`src`	`string`	-	Image source URL, required
`className`	`ClassNameValue`	-	Custom CSS class

Supports all native <img> attributes.

Avatar

On this page