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

F
32
F
48
F
64
F
80
F
[3d]
F
[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 on the fly — 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" />

// in emails, og images, etc.
https://yoursite.com/api/avatar?name=john

props

name

import { Facehash } from "facehash";

<Facehash name="alice" />
<Facehash name="bob" />
<Facehash name="charlie" />
A
"alice"
B
"bob"
C
"charlie"

size

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

colors

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

intensity3d

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

showInitial

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

variant

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

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>
A
image loads
A
image fails
A
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"

C
.

made by cossistant

the open-source chat support widget for react