Blobz

Give any name, username, or ID a face that stays the same. Blobz turns a string into a playful SVG avatar. The same input and palette produce the same character, so your app can render it again without storing an image or calling a service.

Blobz includes a shadcn/ui registry of avatar components and blocks, plus standalone React and TypeScript libraries. The registry components and libraries are free and MIT-licensed. An optional paid hosted image API is available separately; local rendering and registry components require no account, API key, or subscription.

Browse shadcn components · Try the avatar studio · Read the docs · See the packages

In an existing shadcn project, install the Avatar component directly:

npx shadcn@latest add @blobz/avatar

The CLI copies the source into your configured shadcn UI directory and installs its dependencies and status color variables. The Avatar uses Base UI primitives, Tailwind theme tokens, and the familiar shadcn composition API. Its generated fallback renders locally through @blobz/react:

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

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

Add an AvatarImage inside the same Avatar to display an image URL; the generated face appears while the image loads, if it fails, or when no image is supplied. Status badges, unread counts, and avatar groups come from the same module. Profile cards, testimonial cards, person selectors, account menus, team lists, chat panels, and user tables compose these shared primitives with shadcn components.

Verify the integration through the @blobz entry in shadcn's public registry index, the published Avatar registry item, the registry manifest, and the Avatar source. The component and block definitions show the other installable items and their shadcn dependencies.

The standalone npm libraries below also work in projects that do not use shadcn/ui.

bun add @blobz/react

import { Avatar } from "@blobz/react";

export function ProfileAvatar() {
  return (
    <Avatar
      name="janaki-ammal"
      alt="Janaki's avatar"
      palette={["#f2f1f4", "#7c6cf2"]}
      frame="rounded"
      size={64}
    />
  );
}

bun add @blobz/avatar-core

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

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

// svg is the complete image; choices describes the generated face.

The name selects the face. The palette colors it; the frame chooses its crop. Blobz hashes the normalized input into stable feature choices and renders those choices as SVG. There is no random seed to save and no image asset to upload. If you want to pick every feature yourself, use createCustomAvatar or CustomAvatar.

Dodo Payments handles subscriptions for the optional paid hosted API. Varlock validates server configuration; Bun and Turborepo run the workspace. The avatar libraries and installed registry components work without the web app, database, or billing setup.

bun install
bun run dev:web

The site runs at http://localhost:3001. The studio and docs are available without an account. Dashboard and hosted API work need the services listed in apps/web/.env.schema; CONTRIBUTING.md has the local setup and checks. The hosted API guide covers image URLs, origin rules, quotas, and billing operations.

MIT. See LICENSE. The published packages include their own license copies.