Seedface

Modern, framework-agnostic deterministic placeholder avatar generator. Same string → same avatar, forever. One tiny zero-dependency core engine powers React, Vue, Svelte, Web Components and a CLI — plus static SVG/PNG export for emails, OG images and server-rendered lists.

A modern rewrite inspired by nusu/avvvatars (MIT). The 60 base shapes are reused from that project with credit; Seedface adds new shapes, themes, adaptive dark mode, more styles and multi-framework support.

Why Seedface

• ⚡ Zero dependencies in the core. Generates a standalone <svg> string — no CSS-in-JS, no runtime.
• 🧩 Multi-framework: React (RSC-friendly), Vue, Svelte, and a native Web Component.
• 🌗 Adaptive dark mode: every theme ships light + dark palettes; the same user keeps their identity.
• 🎨 7 themes, 69 shapes, and 5 styles: character, shape, gradient, rings, pixel.
• 🖥️ RSC / SSR safe: avatars are pure static markup — render on the server with zero client JS.
• 🏭 Performance at scale: raw SVG generation benchmarks ~100k+ avatars/sec; great for long user lists.
• 🖼️ Static export: a CLI emits SVG or PNG for emails, OG images, favicons, etc.
• 🎬 Subtle, accessible animation: respects prefers-reduced-motion.
• 🔒 Deterministic: cyrb53 hash + mulberry32 PRNG — stable across machines and versions.

Install

Pick your package manager:

NPM

npm i seedface

pnpm

pnpm add seedface

Yarn

yarn add seedface

Bun

bun add seedface

Framework peers (only install what you use):

# React
npm i seedface react react-dom
# Vue
npm i seedface vue
# Svelte
npm i seedface svelte
# PNG export via CLI (optional)
npm i -D @resvg/resvg-js

React (works in Server Components)

import { Avatar } from 'seedface/react';

export function User({ email }: { email: string }) {
  return <Avatar value={email} style="shape" theme="ocean" variant="dark" size={48} shadow animated />;
}

variant="auto" follows prefers-color-scheme. Need the raw string?

import { generateAvatar } from 'seedface';
const { svg, initials, shapeIndex } = generateAvatar({ value: '[email protected]', style: 'pixel' });

Vue

<script setup>
import { Avatar } from 'seedface/vue';
</script>
<template>
  <Avatar value="[email protected]" style="gradient" theme="candy" :size="64" animated />
</template>

Svelte

<script>
  import { Avatar } from 'seedface/svelte';
</script>
<Avatar value="[email protected]" style="rings" theme="neon" size={64} />

Web Component (any framework, or none)

<script type="module">
  import 'seedface/webcomponent'; // auto-registers <seedface-avatar>
</script>
<seedface-avatar value="[email protected]" style="shape" theme="forest" variant="dark" size="64"></seedface-avatar>

import { registerSeedface } from 'seedface/webcomponent';
registerSeedface('my-avatar'); // custom tag name

CLI (static SVG / PNG)

seedface generate --value "[email protected]" --style shape --theme sunset --size 128 --out avatar.svg
seedface generate --value "[email protected]" --out avatar.png --size 256   # needs @resvg/resvg-js

API

generateAvatar(options) → AvatarData

| Option | Type | Default | Notes | | --- | --- | --- | --- | | value | string | — | required seed | | style | character \| shape \| gradient \| rings \| pixel | character | visual style | | size | number | 64 | px (8–512) | | radius | number \| 'full' \| 'none' | full | corner radius | | theme | string | default | see listThemes() | | variant | light \| dark | light | dark adapts the palette | | background / color | string | theme | color overrides | | displayValue | string | derived | force the initials | | border / borderSize / borderColor | boolean / number / string | false / 2 / auto | | | shadow | boolean | false | soft drop shadow | | animated | boolean | false | load + hover animation | | salt | string \| number | — | extra entropy |

Develop

npm install
npm run build   # tsup → dist (esm + cjs + dts)
npm test        # determinism / style / theme checks
npm run demo    # vite playground + showcase site (controls + perf test)

Credits

MIT licensed. Original shapes © Nusu Alabuga & Oguz Yagiz Kara, reused under MIT. Banner art by Molret.