FaceHash
FaceHash is a library for generating deterministic, beautiful, minimalist avatars from any string. It features zero dependencies, pure CSS 3D effects, and is fully typed.
Installation
npm i facehash
# or
yarn add facehash
# or
pnpm add facehash
# or
bun add facehash
Usage
Basic Component
import { Facehash } from "facehash";
// Basic usage
<Facehash name="username" />
Props
| Prop | Type | Default | Description |
|---|---|---|---|
name | string | (Required) | The string to generate the hash from. |
size | number | 64 | Size of the avatar in pixels. |
colors | string[] | random | Array of hex color codes (e.g., ["#264653", "#2a9d8f"]). |
intensity3d | 'none' | 'subtle' | 'medium' | 'dramatic' | 'medium' | Intensity of the 3D effect. |
variant | 'gradient' | 'solid' | 'gradient' | Visual style variant. |
enableBlink | boolean | false | Enables a blinking animation. |
showInitial | boolean | false | Overlay the first letter of the name. |
onRenderMouth | () => ReactNode | undefined | Custom component for the mouth area. |
className | string | undefined | Custom CSS class. |
Examples
// With size and custom colors
<Facehash
name="alice"
size={128}
colors={["#264653", "#2a9d8f", "#e9c46a"]}
/>
// With blinking animation and subtle 3D effect
<Facehash
name="bob"
enableBlink
intensity3d="subtle"
/>
// Solid variant with initial
<Facehash
name="charlie"
variant="solid"
showInitial
/>
Next.js Route Handler
To serve avatars as images (PNG) via a Next.js App Router route handler:
// app/api/avatar/route.ts
import { toFacehashHandler } from "facehash/next";
export const { GET } = toFacehashHandler();
Usage: /api/avatar?name=someName