avataar-me

Deterministic, ultra-fast fallback avatars for React apps.

• 🧑‍🎨 Modes: cartoon (cute character) or initials (clean monogram)
• ⚡️ Instant render: inline SVG (no image fetch on first paint)
• 🗃️ Optional background persist to Supabase Storage + registry table
• 🔎 Built-in lookup: on repeat visits you get a cached CDN URL immediately
• 🧩 Works great with shadcn/ui <Avatar> and any avatar components

This README uses the hosted proxy: https://avatars-proxy.vercel.app
If you self-host, see Centralized backend below.

Table of Contents

• Installation
• Quick Start (shadcn/ui example)
• API
  • <AvataarMe /> props
  • getAvatarUrl(user)
  • Optional runtime config
• How it works
• Centralized backend (recommended to self-host)
  • Supabase (Storage + Edge Functions + Table)
  • Vercel proxy (/ensure, /lookup, /:k.svg)
  • Environment variables
  • End-to-end test
• Alternate: per-app Supabase
• Cartoon generator details
• Performance notes
• Troubleshooting
• Security
• FAQ
• License

Installation

npm i avataar-me
# or
yarn add avataar-me
# or
pnpm add avataar-me

No configuration needed with the hosted proxy.

Quick Start (shadcn/ui example)

"use client";

import { useEffect, useState } from "react";
import { Avatar, AvatarImage, AvatarFallback } from "@/components/ui/avatar";
import { AvataarMe, getAvatarUrl } from "avataar-me";

export default function UserAvatar() {
  const user = { name: "Pritesh Chandra", email: "[email protected]" };
  const [src, setSrc] = useState<string>();

  // Optional: pre-fetch stored CDN URL (repeat visits)
  useEffect(() => {
    (async () => {
      const url = await getAvatarUrl({ name: user.name, email: user.email });
      setSrc(url); // may be undefined on first load; fallback still renders instantly
    })();
  }, [user.name, user.email]);

  return (
    <Avatar className="h-16 w-16">
      {src && <AvatarImage src={src} alt={user.name ?? "avatar"} />}
      <AvatarFallback>
        <AvataarMe
          name={user.name}
          email={user.email}
          mode="cartoon"    // or "initials"
          size={64}
        />
      </AvatarFallback>
    </Avatar>
  );
}

What happens

• First visit: inline SVG renders instantly (no network). A background request persists it.
• Refresh: lookup finds the stored URL and loads from CDN.

API

props

type AvataarMode = "cartoon" | "initials";

type AvataarMeProps = {
  name?: string | null;                  // used for initials + metadata
  email?: string | null;                 // preferred for deterministic key/lookup
  size?: number;                         // px (width=height), default: 48
  mode?: AvataarMode;                    // default: "cartoon"
  ensure?: boolean;                      // persist in background, default: true
  bg?: "solid" | "none";                 // cartoon background, default: "solid"
  variant?: "beam" | "ring" | "grid";    // initials variants
};

Examples

// Cartoon (default)
<AvataarMe name={user.name} email={user.email} size={48} />

// Initials with a variant
<AvataarMe name={user.name} email={user.email} mode="initials" variant="ring" size={40} />

// Inline only (no persistence)
<AvataarMe name={user.name} email={user.email} ensure={false} />

getAvatarUrl(user)

Returns the stored CDN URL if found via the registry; otherwise a deterministic public URL (which will exist after the first persist).

const url = await getAvatarUrl({ name: user.name, email: user.email });

Optional runtime config

If you self-host the proxy and want to override the host at runtime:

import { configureAvataarHost } from "avataar-me";

configureAvataarHost("https://avatars.mycompany.com");
// subsequent calls use this host for /lookup, /ensure, and public URLs