react-usefavicon
v2.0.0
Published
useFavicon: a React Hook to dynamically modify the favicon
Downloads
417
Maintainers
julesblmReadme
react-usefavicon
react-usefavicon is a React hook to dynamically draw on your favicon. Composite badges, text bubbles, progress indicators, or anything you can draw on a canvas onto your existing favicon. This is useful to notify the user of changes or progress, especially if these are long running and the user is expected to switch tabs. GitHub (read more), Slack, and many more websites use this technique.
Works with modern React frameworks: Next.js (App Router & Pages Router), React Router, TanStack Router, Remix, and more. Fully SSR-safe!
React 19 note: If you just need to set a static favicon URL, React 19 supports rendering
<link rel="icon" href={href} />directly in your components — React will hoist it to<head>for you. This hook is most valuable when you need to draw on the favicon using canvas (badges, overlays, dynamic text).
Installing
If you use npm
npm install react-usefaviconFor yarn
yarn add react-usefaviconUsage
import { useFavicon, emojiSvg } from "react-usefavicon";
const { drawOnFavicon, restoreFavicon, setFaviconHref, svgToFavicon } = useFavicon();Returns an object of stable handler functions.
Draw on the favicon
Draw anything on top of the current favicon using the Canvas API. The current favicon is drawn as the background first, then your callback runs on top.
import { useFavicon, drawCircle, drawTextBubble } from "react-usefavicon";
function Notifications({ count }) {
const { drawOnFavicon, restoreFavicon } = useFavicon();
useEffect(() => {
if (count > 0) {
drawOnFavicon(drawCircle, { fillColor: "red", radius: 40, x: 200, y: 200 });
} else {
restoreFavicon();
}
}, [count, drawOnFavicon, restoreFavicon]);
return <span>{count} notifications</span>;
}Or write your own draw callback. It receives the canvas context, the favicon size, and any extra options you pass:
drawOnFavicon((ctx, size) => {
ctx.fillStyle = "green";
ctx.beginPath();
ctx.arc(size - 30, size - 30, 25, 0, Math.PI * 2);
ctx.fill();
});Options
| Option | Type | Default | Description |
|---|---|---|---|
| faviconSize | number | 256 | Canvas size in px |
| clear | boolean | false | Start with a blank canvas instead of drawing over the current favicon |
| ...rest | any | — | Passed through as the third argument to your draw callback |
If you call drawOnFavicon multiple times, drawings stack. Call restoreFavicon() first to draw on the clean original.
Built-in draw functions
Three draw helpers are included for common patterns:
import { drawCircle, drawTextBubble, drawSquare } from "react-usefavicon";drawCircle — draws a filled circle (notification dot)
drawOnFavicon(drawCircle, { fillColor: "red", radius: 40, x: 200, y: 200 });drawTextBubble — draws a rounded badge with a text label (unread count)
drawOnFavicon(drawTextBubble, { label: "3", color: "orangered", fontSize: 128, font: "sans-serif" });drawSquare — draws a filled square
drawOnFavicon(drawSquare, { fillColor: "black", length: 50, x: 200, y: 200 });All options have sensible defaults — you can call drawOnFavicon(drawCircle) with no options for a red dot in the bottom-right corner.
Set an emoji favicon
emojiSvg is a standalone helper — works with the hook or with React 19's <link>:
setFaviconHref(`data:image/svg+xml,${emojiSvg("🔥")}`);
// or without the hook:
<link rel="icon" href={`data:image/svg+xml,${emojiSvg("🔥")}`} />Set a favicon URL
setFaviconHref("/favicons/active.png");Render JSX SVG as favicon
await svgToFavicon(
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
<circle cx="50" cy="50" r="50" fill="tomato" />
</svg>
);This dynamically imports react-dom/server to render the SVG to a string. Only <svg> elements are accepted.
Restore the original favicon
restoreFavicon();Resets the favicon to whatever it was when the hook first mounted.
SSR
The hook is SSR-safe — it no-ops on the server and updates the favicon after hydration. In Next.js App Router, mark the component with 'use client'.
Credits & Inspiration
- Joel Califa: Tiny Wins
- CSS Tricks: Emojis as Favicons
- svg-crowbar
- MDN Canvas tutorial
- favicon-badge
- Tinycon
- react-favicon