lirena00/blobz

Deterministic SVG avatars from any name or ID. React components, a framework-free generator, and a hosted image API

Summary

Blobz is a TypeScript repository that turns a name, username, or ID into a deterministic SVG avatar. The same input and palette produce the same character, so an application can render a stable fallback locally without storing an image or calling a service. It includes React components, a framework-free generator, a shadcn/ui registry, and an optional paid hosted image API.

What it is useful for

Blobz fits products that need default profile images in profile cards, account menus, team lists, chat panels, or user tables. In a React application, @blobz/react provides an Avatar component. The documented example uses name="janaki-ammal", a two-color palette, a rounded frame, and a 64-pixel size.

For code that needs SVG rather than a React component, @blobz/avatar-core exposes createAvatar. It returns the complete SVG string and a choices object describing the generated face. Blobz hashes the normalized input into stable feature choices, so there is no random seed to store and no image asset to upload.

For an existing shadcn/ui project, the registry supplies avatar primitives and blocks. Its generated fallback appears while an image loads, if loading fails, or when no image is supplied. The same module includes status badges, unread counts, and avatar groups. The avatar studio and CustomAvatar support choosing a face manually.

How engineers can use it

In a shadcn/ui project, the README documents:

npx shadcn@latest add @blobz/avatar

This copies the component into the configured shadcn UI directory and installs its dependencies and status color variables. The registry component uses Base UI primitives and Tailwind theme tokens. A typical fallback starts with:

import { Avatar, AvatarFallback } from "@/components/ui/avatar";

export function ProfileAvatar() {
  return (
    <Avatar>
      <AvatarFallback name="janaki-ammal" alt="Janaki's avatar" />
    </Avatar>
  );
}

For a standalone React app, use the documented package:

bun add @blobz/react

For a framework-free integration:

bun add @blobz/avatar-core

Then generate an avatar directly:

import { createAvatar } from "@blobz/avatar-core";

const { svg, choices } = createAvatar({
  name: "janaki-ammal",
  palette: ["#f2f1f4", "#7c6cf2"],
  frame: "rounded",
});

To run the repository’s site locally:

bun install
bun run dev:web

It runs at http://localhost:3001. The studio and documentation work without an account, while dashboard and hosted API work require the services listed in apps/web/.env.schema; consult CONTRIBUTING.md and the hosted API guide for that setup. Local rendering and registry components require no account, API key, or subscription, but the URL-based hosted API is a separate paid service with quotas and billing.