@arraypress/gravatar

Gravatar avatar URLs and profile API. SHA-256 hashing via Web Crypto API. Zero dependencies.

Works in Cloudflare Workers, Node.js 18+, Deno, Bun, and browsers.

Installation

npm install @arraypress/gravatar

Usage

import { getAvatarUrl, getAvatarUrlSync, getProfile } from '@arraypress/gravatar';

// Async — proper SHA-256 hash, matches user's actual Gravatar
const url = await getAvatarUrl('[email protected]');
// → 'https://www.gravatar.com/avatar/abc123...?d=identicon&s=80'

// Sync — simple hash fallback for React render (deterministic identicon)
const url = getAvatarUrlSync('[email protected]');
// → 'https://www.gravatar.com/avatar/1a2b3c...?d=identicon&s=80'

// With pre-computed hash (sync, no await needed)
const url = getAvatarUrl('abc123def456...64chars...', { size: 200 });

// Fetch full profile
const profile = await getProfile('[email protected]');
if (profile) {
  console.log(profile.display_name);
  console.log(profile.avatar_url);
}

API

getAvatarUrl(emailOrHash, options?)

Get a Gravatar avatar URL. Async when given an email (computes SHA-256), sync when given a pre-computed 64-char hex hash.

Options:

• size — Image size in pixels, 1-2048 (default 80)
• default — Fallback image: identicon, mp, monsterid, wavatar, retro, robohash, 404, blank (default identicon)
• rating — Content rating: g, pg, r, x
• forceDefault — Always show the default image

getAvatarUrlSync(email, options?)

Get a Gravatar avatar URL synchronously. Uses a simple numeric hash instead of SHA-256, so the URL will show a deterministic identicon but won't match the user's actual Gravatar. Use getAvatarUrl for accurate results.

Useful in React render functions where you can't await.

hashEmail(email)

Compute the SHA-256 hash of an email address per Gravatar spec (trimmed, lowercased).

const hash = await hashEmail('[email protected]');
// → '31c5543c1734d25c7206f5fd591525d0295bec6fe84ff82f946a34fe970a1e66'

getProfileUrl(email)

Get the Gravatar REST API profile URL for an email.

getProfile(email, options?)

Fetch a Gravatar profile from the v3 REST API. Returns null if not found or on error.

Options:

• token — Gravatar API bearer token for higher rate limits (100/hr unauthenticated, 1000/hr with token)

const profile = await getProfile('[email protected]', { token: 'grav_xxx' });
// { hash, display_name, profile_url, avatar_url, ... }

Sync vs Async

| Function | Hash | Matches actual Gravatar? | Use case | |----------|------|--------------------------|----------| | getAvatarUrl(email) | SHA-256 (async) | Yes | API responses, server-side | | getAvatarUrlSync(email) | Simple hash (sync) | No (shows identicon) | React render, templates | | getAvatarUrl(hash) | Pre-computed (sync) | Yes | When you've cached the hash |

License

MIT