React Favicon Helper

2.0.7 · active · verified Sun Apr 19

react-favicon is a React component that enables dynamic control over a web application's favicon. It allows developers to easily update the favicon image using a URL or a base64 encoded string, integrate animated sequences from a list of URLs, toggle these animations on and off, and display alert bubbles with customizable text and background colors directly on the favicon. Additionally, it supports custom icon overlays through a render function and offers a mechanism to preserve existing favicon links on the page, which can be beneficial for specific browser behaviors like desktop Safari. The package is currently at version 2.0.7 and appears to have an active release cadence, with recent updates ensuring compatibility with React 19 and addressing various internal component optimizations. Its key differentiator lies in providing a declarative, React-idiomatic way to manage complex favicon behaviors, moving beyond simple static <link> tags, making it suitable for applications requiring dynamic visual feedback in the browser tab.

Common errors

```
TypeError: Favicon is not a function
```
cause Attempting to import `Favicon` using CommonJS `require` syntax in an environment expecting ESM, or a bundler misconfiguration.

fix Use ESM `import Favicon from 'react-favicon';` in your JavaScript/TypeScript files.
```
Property 'url' is missing in type '{}' but required in type 'FaviconProps'.
```
cause When using TypeScript, the required `url` prop was not provided to the `Favicon` component.

fix Ensure you pass the `url` prop: `<Favicon url="https://example.com/favicon.ico" />` or `<Favicon url={['url1', 'url2']} />`.
```
Cannot read properties of undefined (reading 'alertCount')
```
cause A prop that has `null` as its default in the component is being accessed directly without a null-check, or an internal assumption about `defaultProps` was broken by a patch update.

fix Ensure all props are explicitly passed or correctly default to prevent `undefined` values, especially for props like `alertCount`, `alertFillColor`, etc.

Warnings

breaking Version 2.0.0 introduced a rewrite to React's functional component API and a new build system. While the public API was intended to remain compatible, internal changes might affect projects with specific bundler configurations or reliance on pre-v2 internal behaviors.
Fix: Review your bundler configuration for ESM/CJS compatibility. If issues arise, report bugs to the maintainers, as API breakage was not intended.
gotcha The `defaultProps` functionality was inconsistently handled across patch versions 2.0.4, 2.0.5, and 2.0.6 due to fixes and reverts related to issue #54. Relying on implicit `defaultProps` might lead to unexpected behavior or regressions in specific patch versions.
Fix: Always explicitly pass all required props to the `Favicon` component, or define default values within your consuming component, rather than relying solely on the library's `defaultProps`.
gotcha The `keepIconLink` prop defaults to `() => false`. This means `react-favicon` will remove existing favicon links from the document head when it takes control. If you intend to preserve pre-existing favicons (e.g., for specific browser behaviors like desktop Safari or during initial page load), you must explicitly set this prop.
Fix: Pass `keepIconLink={() => true}` to the `Favicon` component if you wish to prevent it from removing other favicon `<link>` tags in the document head.
gotcha The `url` prop is required and expects either a `string` for a static favicon or a `string[]` for an animated sequence. Providing `null`, `undefined`, or an invalid type will prevent the favicon from updating or may cause runtime errors.
Fix: Ensure the `url` prop is always provided and is of type `string` or `string[]`.

Install

npm install react-favicon npm
yarn add react-favicon yarn
pnpm add react-favicon pnpm

Imports

Favicon
wrong:
```
const Favicon = require('react-favicon');
```
correct:
```
import Favicon from 'react-favicon';
```
Primary component import. CommonJS 'require' style is generally incorrect in modern React/ESM projects.
FaviconProps
```
import type { FaviconProps } from 'react-favicon';
```
Type import for component props when using TypeScript.
Favicon (with alias)
```
import MyFavicon from 'react-favicon';
```
You can alias the default import if 'Favicon' conflicts with another symbol.

Quickstart

Demonstrates basic `Favicon` usage with a static URL and an animated sequence, updating the browser tab's icon dynamically. Includes basic error handling for root element.

import React from "react";
import ReactDOM from "react-dom";
import Favicon from "react-favicon";

function App() {
  const githubFaviconUrl = "http://oflisback.github.io/react-favicon/img/github.ico";
  const animatedFavicons = [
    "http://oflisback.github.io/react-favicon/img/github.ico",
    "https://www.google.com/favicon.ico",
    "https://www.npmjs.com/favicon.ico"
  ];

  return (
    <div>
      <Favicon url={githubFaviconUrl} />
      <h1>Hello, Favicon!</h1>
      <p>This component dynamically sets the favicon for your page.</p>
      <p>
        You can also animate it or show alerts. Here's an animated example:
      </p>
      <Favicon url={animatedFavicons} animated={true} animationDelay={1000} />
      <p>Check your browser tab to see the favicon change every second!</p>
    </div>
  );
}

// Assumes an HTML element with id="root" exists.
const rootElement = document.getElementById("root");
if (rootElement) {
  ReactDOM.render(
    <App />,
    rootElement
  );
} else {
  console.error("Root element not found. Please ensure an element with id='root' exists in your HTML.");
}

view raw JSON →