facehash

Deterministic avatar faces from any string. Zero dependencies, works with React 18/19 and Next.js 15/16.

Installation

``bash
npm install facehash
`

Quick Start

$3

`tsx
import { Facehash } from "facehash";


`

Same string = same face. Always.

$3

Generate PNG avatar images via API endpoint — perfect for emails, Open Graph images, or anywhere you need a URL.

`tsx
// app/api/avatar/route.ts
import { toFacehashHandler } from "facehash/next";

export const { GET } = toFacehashHandler();
`

Then use it:
`
GET /api/avatar?name=john@example.com
GET /api/avatar?name=john&size=200&variant=solid
`

Returns a PNG image. Cached for 1 year by default.

Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| name | string | Required | String to generate face from |
| size | number \| string | 40 | Size in pixels or CSS units |
| colors | string[] | - | Array of hex/hsl colors |
| colorClasses | string[] | - | Array of Tailwind classes (use instead of colors) |
| variant | "gradient" \| "solid" | "gradient" | Background style |
| intensity3d | "none" \| "subtle" \| "medium" \| "dramatic" | "dramatic" | 3D rotation effect |
| interactive | boolean | true | Animate on hover |
| showInitial | boolean | true | Show first letter below face |
| onRenderMouth | () => React.ReactNode | - | Custom mouth renderer (replaces initial) |
| enableBlink | boolean | false | Enable random eye blinking animation |

Examples

$3

`tsx
name="alice"
colors={["#264653", "#2a9d8f", "#e9c46a", "#f4a261", "#e76f51"]}
/>
`

$3

`tsx
name="bob"
colorClasses={["bg-pink-500", "bg-blue-500", "bg-green-500"]}
className="rounded-full"
/>
`

$3

`tsx

`

$3

`tsx

`

$3

Add a subtle, chaotic blinking effect to make faces feel alive:

`tsx

`

The blinking is pure CSS with randomized timing per eye — each eye blinks at different intervals for a natural, chaotic effect.

$3

Replace the initial letter with any custom component:

`tsx
import { Facehash } from "facehash";
import { Spinner } from "./spinner"; // Your loading spinner

// Show a spinner as the "mouth"
name="loading"
onRenderMouth={() => }
/>

// Custom icon
name="bot"
onRenderMouth={() => }
/>

// Combine with blinking for a "thinking" avatar
name="thinking"
enableBlink
onRenderMouth={() => }
/>
`

Avatar with Image Fallback

For image avatars that fall back to Facehash when the image fails:

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





`

AvatarFallback renders a Facehash by default. For initials instead:

`tsx

`

Next.js API Route

The facehash/next export provides a route handler factory for generating avatar images server-side. This is useful for:

- Email avatars (where you need an image URL)
- Open Graph / social sharing images
- Any context where you need a URL instead of a React component

$3

`tsx
// app/api/avatar/route.ts
import { toFacehashHandler } from "facehash/next";

export const { GET } = toFacehashHandler();
`

$3

`tsx
export const { GET } = toFacehashHandler({
size: 200, // Default image size (default: 400)
variant: "solid", // "gradient" | "solid" (default: "gradient")
showInitial: false, // Show first letter (default: true)
colors: ["#ff6b6b", "#4ecdc4", "#45b7d1"], // Custom color palette
cacheControl: "public, max-age=86400", // Custom cache header
});
`

$3

All options can be overridden via URL query parameters:

| Parameter | Type | Description |
|-----------|------|-------------|
| name | string | Required. String to generate avatar from |
| size | number | Image size in pixels (16-2000) |
| variant | string | "gradient" or "solid" |
| showInitial | boolean | "true" or "false" |
| colors | string | Comma-separated hex colors (e.g., #ff0000,#00ff00) |

$3

`
/api/avatar?name=john@example.com
/api/avatar?name=Alice&size=128
/api/avatar?name=Bob&variant=solid&showInitial=false
/api/avatar?name=Team&colors=%23ff6b6b,%234ecdc4,%2345b7d1
`

$3

By default, responses include Cache-Control: public, max-age=31536000, immutable (1 year). Same name always generates the same image, so aggressive caching is safe.

Exports

`tsx
// Main component
import { Facehash } from "facehash";

// Avatar compound components
import { Avatar, AvatarImage, AvatarFallback } from "facehash";

// Individual face components (for custom use)
import { RoundFace, CrossFace, LineFace, CurvedFace, FACES } from "facehash";

// Utilities
import { stringHash } from "facehash";

// Types
import type { FacehashProps, AvatarProps, AvatarFallbackProps, AvatarImageProps } from "facehash";

// Next.js route handler (facehash/next)
import { toFacehashHandler } from "facehash/next";
import type { FacehashHandlerOptions, FacehashHandler } from "facehash/next";
``

License

MIT — Built by Cossistant