React Package Documentation

Updated at: November 1, 2025

Build beautiful interfaces with @favicolor/react components

Features

The @favicolor/react package offers many advanced features:

Flexible sizes

Accepts any size between 32 and 128 pixels, automatically rounded to optimal API size

Retina/HiDPI detection

Automatically loads 2x images on high-resolution displays (Retina, 4K, etc.)

Dynamic DPI detection

Automatically recalculates image when window is moved between displays with different resolutions

Elegant fallback

Displays a default globe icon if favicon is not found

Smart cache

Colors are cached, image URLs are dynamically calculated based on DPR

Light/dark themes

Native support for both themes with optimized colors

Strict TypeScript

Strict typing for all props and interfaces

SSR-safe

Compatible with Next.js and other SSR frameworks

Adaptive inline

FavicolorInlineIcon automatically adapts to text size

Installation

Install the package via your preferred package manager:

npm install @favicolor/react

Configuration

Wrap your application with FavicolorProvider to configure API access:

TypeScript
1
import { FavicolorProvider } from '@favicolor/react';
2
3
function App() {
4
  return  (
5
    <FavicolorProvider
6
      config={{
7
        apiUrl: 'https://api.favicolor.com', // Optionnel
8
        apiKey: process.env.NEXT_PUBLIC_FAVICOLOR_API_KEY, // Pour localhost
9
        appId: process.env.NEXT_PUBLIC_FAVICOLOR_APP_ID, // Pour production
10
        defaultTheme: 'dark', // 'light' ou 'dark'
11
        defaultSize: 64, // Taille entre 32 et 128 pixels
12
        enableRetina: true, // Active la détection Retina (défaut: true)
13
      }}
14
    >
15
      <YourApp />
16
    </FavicolorProvider>
17
  );
18
}

Configuration Options

OptionTypeDefaultDescription
apiUrlstringhttps://api.favicolor.comFavicolor API URL
apiKeystringundefinedAPI key for requests from localhost (development)
appIdstringundefinedApplication ID for requests from registered domains (production)
defaultTheme'light' | 'dark''dark'Default theme for all components
defaultSizenumber64Default icon size in pixels (between 32 and 128)
enableRetinabooleantrueEnables automatic detection of Retina/HiDPI displays

Authentication

The package automatically handles authentication based on your environment:

  • apiKey: Used automatically for requests from localhost (development)
  • appId: Used for requests from registered domains (production)

Components

FavicolorIcon

Displays a favicon in a squircle container with colors automatically extracted by the API.

Props

PropTypeRequiredDescription
urlstringrequiredFull URL or domain name
sizenumberoptionalImage size in pixels (between 32 and 128). Automatically rounded to optimal API size
theme'light' | 'dark'optionalColor theme
classNamestringoptionalAdditional CSS classes
fallbackReactNodeoptionalCustom fallback component
shape'circle' | 'square' | 'squircle' | 'custom' | 'auto'optionalContainer shape
Interactive Example
32px56px80px104px128px
github.com (64px)

Code Example

TypeScript
1
import { FavicolorIcon } from '@favicolor/react';
2
3
function MyComponent() {
4
  return  (
5
    <FavicolorIcon
6
      url="https://github.com"
7
      size={64}
8
      theme="dark"
9
      className="hover:scale-110 transition-transform"
10
    />
11
  );
12
}

FavicolorInlineIcon

Inline icon with adaptive em sizing to naturally integrate with text.

Props

PropTypeRequiredDescription
urlstringrequiredFull URL or domain name
theme'light' | 'dark'optionalColor theme
classNamestringoptionalAdditional CSS classes
styleCSSPropertiesoptionalInline CSS styles (e.g., width: '1.5em')
Interactive Example
12px16px20px24px28px

Visitez GitHub

Code Example

TypeScript
1
import { FavicolorInlineIcon } from '@favicolor/react';
2
3
function MyText() {
4
  return  (
5
    <p className="text-lg">
6
      Visitez <FavicolorInlineIcon url="github.com" /> GitHub
7
    </p>
8
  );
9
}

FavicolorLink

Link with automatic inline favicon.

Props

PropTypeRequiredDescription
hrefstringrequiredDestination URL
childrenReactNoderequiredLink content
iconPosition'left' | 'right'optionalIcon position
showIconbooleanoptionalDisplay icon
classNamestringoptionalAdditional CSS classes
iconClassNamestringoptionalAdditional CSS classes
iconStyleCSSPropertiesoptionalInline CSS styles (e.g., width: '1.5em')
targetstringoptionalLink target attribute
relstringoptionalLink rel attribute
Interactive Example
12px16px20px24px28px

Code Example

TypeScript
1
import { FavicolorLink } from '@favicolor/react';
2
3
function MyLinks() {
4
  return  (
5
    <div>
6
      <FavicolorLink href="https://github.com">
7
        Visitez GitHub
8
      </FavicolorLink>
9
10
      <FavicolorLink
11
        href="https://google.com"
12
        iconPosition="right"
13
        className="text-blue-500 hover:underline"
14
      >
15
        Rechercher
16
      </FavicolorLink>
17
    </div>
18
  );
19
}

Hook

useFavicolor

React hook to access Favicolor configuration from context.

Usage Example

TypeScript
1
import { useFavicolor } from '@favicolor/react';
2
3
function MyComponent() {
4
  const config = useFavicolor();
5
  console.log(config.apiUrl); // 'https://api.favicolor.com'
6
  console.log(config.defaultTheme); // 'dark'
7
}

The hook returns the complete FavicolorProvider configuration, allowing you to access all configured options.

Retina/HiDPI Optimization

How does it work?

1. Automatic detection

The component detects the screen DPR (window.devicePixelRatio)

2. Smart calculation

API size is automatically calculated: displaySize × min(DPR, 2)

3. Optimal rounding

Rounds up to nearest API size (32, 64, 96, 128) to avoid upscaling

4. 2x cap

DPR is capped at 2x maximum to optimize bandwidth

Examples

<FavicolorIcon url="github.com" size={64} />
// → Charge une image 64×64 pixels

Disable Retina detection

If you want to disable Retina detection (e.g., to save bandwidth), pass enableRetina: false in the Provider configuration.

TypeScript
1
<FavicolorProvider
2
  config={{
3
    enableRetina: false, // Désactive la détection Retina
4
  }}
5
>
6
  <App />
7
</FavicolorProvider>

Dynamic screen change detection

The component automatically listens for resolution changes via matchMedia. When you move the window from a standard display to a Retina display (or vice-versa), the image is automatically recalculated and reloaded.

Documentation center | Favicolor