FACEHASH

byCossistant Logocossistant

a React component that generates unique avatar faces from any string. zero dependencies. works with Next.js, Vite, Remix.

$ npm i facehash

try it — type anything

32
48
64
80
[3d]
[flat]
[no letter]

why facehash?

every app needs avatars. most solutions are either too heavy, require external services, or look dated. facehash generates unique, friendly faces from any string — emails, usernames, uuids, whatever.

same input = same face. always. no api calls, no storage, no randomness. just deterministic, beautiful avatars that work offline.

need an image URL for emails or og images? use the next.js route handler to generate PNGs by default or raw SVGs for icons and favicons — cached forever.

perfect for user profiles, comment sections, chat apps, and ai agents — give your bots a face that's consistent across sessions.

0kb
no external assets
api
next.js image route
a11y
accessible by default
ts
fully typed
how to use with React?
import { Facehash } from "facehash";

<Facehash name="agent-47" size={48} />
need an image URL instead?
// app/api/avatar/route.ts
import { toFacehashHandler } from "facehash/next";

export const { GET } = toFacehashHandler();
// use it anywhere you need a URL
<img src="/api/avatar?name=john" />

// raw svg for icons, favicons, or browser UI
https://yoursite.com/api/avatar?name=john&format=svg&pose=front

props

name

import { Facehash } from "facehash";

<Facehash name="alice" />
<Facehash name="bob" />
<Facehash name="charlie" />
"alice"
"bob"
"charlie"

size

<Facehash name="facehash" size={32} />
<Facehash name="facehash" size={48} />
<Facehash name="facehash" size={64} />
32
40(default)
48
64

colors

<Facehash name="facehash" colors={["#264653", "#2a9d8f", "#e9c46a"]} />
default
custom

intensity3d

<Facehash name="facehash" intensity3d="none" />
<Facehash name="facehash" intensity3d="subtle" />
<Facehash name="facehash" intensity3d="dramatic" />
none
subtle
medium
dramatic(default)

showInitial

<Facehash name="facehash" showInitial={true} />
<Facehash name="facehash" showInitial={false} />
true(default)
false

variant

<Facehash name="facehash" variant="gradient" />
<Facehash name="facehash" variant="solid" />
gradient(default)
solid

enableBlink

<Facehash name="facehash" enableBlink />
<Facehash name="alice" enableBlink />
<Facehash name="bob" enableBlink />
false(default)
true
"alice"
"bob"

onRenderMouth

<Facehash name="loading" onRenderMouth={() => <Spinner />} />
<Facehash name="thinking" enableBlink onRenderMouth={() => <Spinner />} />
default
spinner
thinking

className (styling)

// Style face color and font with Tailwind classes
<Facehash name="ghost" className="text-white" />

// For app-wide defaults, create a wrapper with tailwind-merge:
import { Facehash, type FacehashProps } from "facehash";
import { cn } from "@/lib/utils";

export function Avatar({ className, ...props }: FacehashProps) {
  return (
    <Facehash
      className={cn("text-black font-pixel font-bold", className)}
      {...props}
    />
  );
}

// Now overrides work naturally:
<Avatar name="user" />                        // defaults
<Avatar name="user" className="text-red-500" /> // red color
default
text-white
font-sans

need an image with fallback? use the Avatar wrapper:

Avatar

import { Avatar, AvatarImage, AvatarFallback } from "facehash";

<Avatar>
  <AvatarImage src="/photo.jpg" />
  <AvatarFallback name="anthony" />
</Avatar>
image loads
image fails
no image

use cases

user profiles, chat apps, comment sections, team directories, multiplayer games, placeholder avatars, bot identities, even AI agents like that one you randomly named "Claude"

.

made by cossistant

the open-source chat support widget for react