How It Works

From URL to favicon in milliseconds. Here's what happens behind the scenes.

You Add a Link Tag

When a browser loads your page, it sees this tag and makes a request to emojifavicons.com/fire to fetch the favicon.

We Resolve the Emoji

Our Cloudflare Worker receives the request and resolves fire to the emoji character. The resolution happens in three steps:

Direct emoji check - If the URL contains an actual emoji character (URL-encoded), we use it directly
Flag detection - Regional indicator pairs like US resolve to flag emojis
Keyword lookup - Names and keywords are matched against a table of 11,550 entries covering all 3,773 emojis

The keyword table includes official Unicode names, common synonyms, and related terms. Searching /hot finds the fire emoji. Searching /happy finds the grinning face.

We Generate an SVG (or PNG for Safari)

The emoji gets wrapped in a minimal SVG. The entire response is under 200 bytes:

<svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 16 16"><text x="0" y="14">🔥</text></svg>

SVG favicons are supported by all modern browsers. The <text> element renders the emoji using the system's native emoji font.

Safari compatibility: Safari has issues rendering emoji in SVG <text> elements as favicons. We detect Safari via User-Agent and automatically serve a 72x72 PNG from the Twemoji library instead. No action needed on your part.

You can override the format with query parameters: append ?svg to force SVG or ?png to force PNG.

Caching Kicks In

The response includes cache headers that prevent unnecessary re-fetches:

CDN cache: 7 days - Cloudflare caches the SVG at 300+ edge locations worldwide. Subsequent requests from the same region are served instantly.
Browser cache: 24 hours - The user's browser stores the favicon locally. Return visits don't make any network request at all.

This means the first visitor from a region triggers one request to our worker. Everyone after that gets a cached response with zero latency.

Usage Gets Tracked

Every favicon request increments an in-memory counter for that emoji. We also record the requesting country (from Cloudflare headers) and the referrer domain (which site is using the favicon).

Counters are synced periodically to maintain accurate, real-time-ish statistics with minimal overhead.

The public analytics page shows all tracked data: top emojis, country flags, requesting countries, and referrer domains.

URL Formats

All of these work:

/fire - Emoji name
/hot - Related keyword
/🔥 - Actual emoji character (URL-encoded)
/point-right - Hyphenated names
/US - Country code for flags
/fire+rocket - Combo emojis (two side-by-side)

Names and keywords are case-insensitive. Maximum URL length is 200 characters.

Format control:

/fire?svg - Force SVG output (useful for CSS cursors)
/fire?png - Force PNG output (72x72 Twemoji)

URL Parameters

Customize any favicon with query parameters:

?size=64 - Custom size in pixels (16-512, default 48)
?bg=1a1a1a - Background color (hex, no # prefix)
?darkbg=ffffff - Dark mode background (uses prefers-color-scheme)
?shape=circle - Background shape: circle or rounded
?animate=pulse - Animation: pulse, bounce, or spin
?align=center - Emoji alignment: center, top-left, top, top-right, left, right, bottom-left, bottom, bottom-right
?og=true - OG image mode (1200x630 SVG for social sharing)

Combine them freely: /fire?size=64&bg=1a1a1a&animate=pulse

API

Get usage stats as JSON:

curl https://emojifavicons.com/api/stats

Returns top emojis with counts, country flag stats, referrer domains, country breakdown, and total served count.

Search emojis by name or keyword:

curl https://emojifavicons.com/api/search?q=fire

Returns up to 20 matching emojis with name, slug, category, keywords, and direct URL. Cached for 1 hour.

JavaScript SDK

Tiny client-side SDK for dynamic favicons:

Then use it in your JavaScript:

EmojiFavicon.set('fire') // Set favicon
EmojiFavicon.set('fire', {bg:'1a1a1a'}) // With options
EmojiFavicon.animate('rocket', 'spin') // Animated
EmojiFavicon.notify('bell', 3000) // Flash for 3s
EmojiFavicon.restore() // Restore original

Badge Endpoint

Shields.io-style badges with emoji. Perfect for GitHub READMEs:

![Status](https://emojifavicons.com/badge/rocket?label=deploy&status=live&color=green)

Parameters:

label - Left side text (default: emoji name)
status - Right side text
color - Right bg: green, red, yellow, blue, or hex
labelColor - Left bg (hex)
style - flat or rounded

/badge/fire?label=build&status=passing&color=green
/badge/rocket?label=deploy&status=v2.1&color=blue
/badge/warning?label=security&status=critical&color=red

Avatar Endpoint

Gravatar-style deterministic emoji avatars. Hash any identifier (email, username, ID) to a consistent emoji + color:

<img src="https://emojifavicons.com/avatar/user@example.com?shape=circle&size=128">

Parameters:

size - Size in pixels (16-512, default 128)
shape - 16 shapes: square, circle, rounded, hexagon, diamond, shield, star, heart, triangle, pentagon, octagon, drop, egg, cross, cloud, badge

Same identifier always produces the same emoji and background color. Cached for 30 days.

README Banner

800x200 SVG banners for GitHub READMEs:

![Banner](https://emojifavicons.com/readme/rocket?title=My+Project&subtitle=Fast+and+simple&theme=dark)

Parameters:

title - Main text (default: emoji name)
subtitle - Secondary text
theme - dark (default) or light

Status Icons

Predefined status indicators for dashboards and status pages:

/status/up 🟢 Green circle (service up)
/status/down 🔴 Red circle (service down)
/status/degraded 🟡 Yellow circle (degraded)
/status/maintenance 🔧 Wrench (maintenance mode)

Override the default emoji with ?emoji=rocket. Set size with ?size=24.

Usage: <img src="https://emojifavicons.com/status/up" width="16"> All systems operational

Suggest API

Get emoji suggestions for a topic or URL. Great for "what emoji should I use?" features:

curl https://emojifavicons.com/api/suggest?text=cooking+blog

Or analyze a website:

curl https://emojifavicons.com/api/suggest?url=https://example.com

Returns up to 8 suggestions ranked by relevance score, with emoji, name, slug, and direct URL.

Emoji of the Day

A deterministic daily emoji. Same emoji for everyone on the same day:

curl https://emojifavicons.com/api/eotd

Returns emoji, name, slug, category, date, SVG URL, and badge URL. Great for bots, newsletters, and daily content.

Email Signature

PNG emoji for email clients that don't support SVG:

Returns a PNG with Content-Disposition: inline. Default size 32px. Works in Gmail, Outlook, and Apple Mail.

Domain Attribution (v7.1)

Opt-in attribution: append ?ref=yourdomain.com to any emoji URL to register your domain as a verified user of the service.

Registered domains appear in the public Showcase Directory, a browsable gallery of sites using emoji favicons. After copying an emoji URL, the SmartCopyDialog prompts you to register your domain in one click.

APIs: /api/validate-domain?domain=... validates DNS, POST /api/register-domain registers a domain, /api/showcase lists the directory. See the full documentation.

More Endpoints

/embed/:emoji - Minimal HTML page with centered emoji. For Notion, iframes, embeds.
/oembed?url=... - oEmbed discovery for rich embeds.
/feed.xml - Atom feed of trending emojis. For RSS readers and bots.
/llms.txt - Plain text API description for AI agents.
/.well-known/ai-plugin.json - ChatGPT/GPT Actions plugin manifest.
/openapi.yaml - OpenAPI 3.1 spec for tool integrations.
/robots.txt - Crawler directives + sitemap reference.
/sitemap.xml - XML sitemap for search engines.