✨ Open Source · MIT License

Beautiful PNG Avatars
for Every Project

Deterministic, illustrated avatars. Pass a seed, get the same avatar every time. No API, no server required.

$ npm install quick-avatar

click to copy

🎲

Deterministic

Same seed always produces the same avatar. Perfect for user profiles — consistent across sessions and devices.

📦

No API Required

Everything ships inside the npm package. Works offline, in private networks, and with zero latency.

⚡

Zero Initial Bundle

Core logic is ~5 KB. Images are lazy-loaded as separate chunks — your app only downloads what it renders.

🖼

PNG Illustrations

Hand-crafted character portraits, not geometric patterns. Real artists, real style — transparent backgrounds available.

Try It

Playground

Type any seed — an email, username, or user ID — and see your avatar in real time.

Avatar preview
Index: —  /  Set: —
Collections

Style Sets

Click any avatar to copy its CDN URL. All characters are crafted as illustrated portraits.

Install & Use

Usage

Works in any JavaScript environment — React, Vue, Node.js, or plain HTML.

// Install once
// npm install quick-avatar

import { createAvatar, doteye, doteyeAlpha, doteyePaper } from 'quick-avatar';

// Solid white background
const avatar = createAvatar(doteye, { seed: 'user@example.com' });
const src = await avatar.toDataUri();
// → "data:image/png;base64,..."

// Transparent background
const avatarAlpha = createAvatar(doteyeAlpha, { seed: 'user@example.com' });

// Black & white, transparent background
const avatarPaper = createAvatar(doteyePaper, { seed: 'user@example.com' });
<!-- No install needed — link directly from jsDelivr -->

<!-- With JavaScript hash -->
<script>
  function quickAvatarUrl(seed, set = 'doteye') {
    let h = 5381;
    for (let i = 0; i < seed.length; i++)
      h = ((h << 5) + h) ^ seed.charCodeAt(i), h = h >>> 0;
    const idx = h % 64;
    return `https://cdn.jsdelivr.net/npm/quick-avatar/dist/sets/${set}/images/${idx}.png`;
  }

  document.getElementById('avatar').src = quickAvatarUrl('user@example.com');
</script>

<img id="avatar" width="64" height="64" />
import { useEffect, useState } from 'react';
import { createAvatar, doteye, doteyeAlpha, doteyePaper } from 'quick-avatar';

const sets = { doteye, doteyeAlpha, doteyePaper };

function Avatar({ userId, style = 'doteye' }) {
  const [src, setSrc] = useState('');
  const set = sets[style];

  useEffect(() => {
    createAvatar(set, { seed: userId }).toDataUri().then(setSrc);
  }, [userId, style]);

  return <img src={src} width={64} height={64} alt="avatar" />;
}

// Usage
<Avatar userId="user-123" />
<Avatar userId="user-123" style="doteyeAlpha" />
<Avatar userId="user-123" style="doteyePaper" />
// Works in Expo and bare React Native
// Data URIs are natively supported by RN's Image component

import { useEffect, useState } from 'react';
import { Image, StyleSheet } from 'react-native';
import { createAvatar, doteye, doteyeAlpha, doteyePaper } from 'quick-avatar';

const sets = { doteye, doteyeAlpha, doteyePaper };

function Avatar({ userId, style = 'doteye', size = 64 }) {
  const [uri, setUri] = useState(null);

  useEffect(() => {
    createAvatar(sets[style], { seed: userId })
      .toDataUri()
      .then(setUri);
  }, [userId, style]);

  if (!uri) return null;

  return (
    <Image
      source={{ uri }}
      style={[styles.avatar, { width: size, height: size, borderRadius: size / 2 }]}
    />
  );
}

const styles = StyleSheet.create({
  avatar: { backgroundColor: '#f1f5f9' },
});

// Usage
<Avatar userId="user-123" />
<Avatar userId="user-123" style="doteyeAlpha" size={80} />
import { createAvatar, doteye } from 'quick-avatar';
import fs from 'fs';

const avatar = createAvatar(doteye, { seed: req.user.id });

// Serve as HTTP response
res.setHeader('Content-Type', 'image/png');
res.end(avatar.toBuffer());

// Or get absolute file path
const path = avatar.toFilePath();

// Or use data URI in emails / HTML generation
const dataUri = await avatar.toDataUri();
Copied!