Make your favicon great again!

🍤 Tiny

Small footprint ~ 2kb which makes your apps faster to load

🦾 DX Friendly

Written in TypeScript

🍞 Easy to use

It's easy to use and has many options to customize

Quick Setup

Installation 🚀

# install with yarn
yarn add favoritos

# install with npm
npm install favoritos --save

Or use a CDN

<script src="https://unpkg.com/favoritos@1.0.1/dist/favoritos.iife.js"></script>
or
<script src="https://cdn.jsdelivr.net/npm/favoritos@1.0.1/dist/favoritos.iife.js"></script>

Hint: for a better performance add preconnect link in the head of your document.

<head>
  <!-- for unkpg cdn --> 
  <link rel="preconnect" href="https://unpkg.com">

  <!-- for jsdelivr cdn -->
  <link rel="preconnect" href="https://cdn.jsdelivr.net">  


  <!-- dns-prefetch only for IE11 --> 
  <!--  <link rel="dns-prefetch" href="https://unpkg.com"> -->
  <!--  <link rel="dns-prefetch" href="https://cdn.jsdelivr.net"> -->
</head>

Usage 🤔

1. Initialize favoritos

Option A: Using ES 2015:
import Favoritos from 'favoritos';

const favoritos = new Favoritos({
  icon: {
    // Your options
  },
  badge: {
    // Your options
  },
  debug: {
    // Your options
  },
});
Option B: Using CommonJS:
const Favoritos = require('favoritos');

const favoritos = new Favoritos({
  icon: {
    // Your options
  },
  badge: {
    // Your options
  },
  debug: {
    // Your options
  },
});
Option C: Using CDN:
/* Favoritos is available from global namespace */
const favoritos = new Favoritos({
  icon: {
    // Your options
  },
  badge: {
    // Your options
  },
  debug: {
    // Your options
  },
});

2. Add magic to your favicon

Options
Icon options
Option Default value Description
iconSelector 'link[rel*="icon"]' A selector for your favicon where magic will be drawn.
backgroundColor '#d21f3c' Background color for the icon. Used when rendering the progress bar. May be a string or an array. If an array is passed, a gradient will be drawn.
shape 'circle' The shape for the icon. Can take the following values: circle, rect.
lineWidth 4 Line width for your icon.
width 32 Width for your icon. Initially, there is the width of a standard favicon.
height 32 Height for your icon. Initially, there is the height of a standard favicon.
Badge options
Option Default value Description
fontSize 18 Font size of badge text.
backgroundColor '#d21f3c' Background color for the badge.
fontFamily 'Helvetica, Arial, sans-serif' Font family for the badge text.
shape 'circle' The shape for the icon. Can take the following values: circle, rect.
position 'bottom-right' Position for your badge. Can take the following values: top-left, top-right, bottom-left, bottom-right.
minWidth 22 Minimal width for your badge.
minHeight 22 Minimal height for your icon.
Debug options

Debug mode can be useful if you want to look at the favicon near

Option Default value Description
enabled false Turns debugging on and off.
debugSelector '#favoritos-debug' Element selector where the canvas will be drawn.

3. Call methods

favoritos.drawBadge()

favoritos.drawBadge('')

favoritos.drawBadge(1)

favoritos.drawBadge(123)

Draws a badge on top of the favicon. With an empty string – an empty badge will be drawn. You can also pass numbers.

favoritos.drawImage()

/* Image example */
const img = document.querySelector('.my-image');
favoritos.drawImage(img)

/* Video example */
const video = document.querySelector('.my-video');
video.addEventListener('play', function () {
function step() {
  favoritos.drawImage(video)
  requestAnimationFrame(step)
}
requestAnimationFrame(step);
})

Draws a picture or video instead of your favicon. Takes one argument - the content to be drawn. Image or video must have crossorigin="anonymous" attribute

favoritos.drawProgress()

/* Scroll progress example */
document.addEventListener('scroll', () => {
  const root = document.documentElement;
  const scrollTopInPx = root.scrollTop;
  const pageHeightInPx = root.scrollHeight - root.clientHeight;
  const scrollPercent = (scrollTopInPx / pageHeightInPx) * 100;
  const scrollPercentRounded = Math.round(scrollPercent);
  
  favoritos.drawProgressBar(scrollPercentRounded);
})

/* XHR example */
const formData = new FormData();
formData.append('files', /* Your data */);
const xhr = new XMLHttpRequest();

xhr.open('POST', '');
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');

xhr.upload.addEventListener('progress', (event) => {
  if (event.lengthComputable) {
    const complete = (event.loaded / event.total * 100 | 0);
    favoritos.drawProgressBar(complete);
  }
});

xhr.send(formData);

Allows you to draw a progress bar instead of your icon. The progress bar shape depends on the option shape passed during library initialization.

The method takes two arguments: progress and useFavicon. progress indicates how much has already been completed. Value from 0 to 100. useFavicon indicates whether to draw the progress bar on top of the favicon.

favoritos.setOptions()

/* For example, set icon background color to green if task was done */
favoritos.setOptions({
  icon: {
    backgroundColor: 'green'
  }
})

You can change any options for the library. But after the change, you must definitely call the icon renderer with the method of which you use (drawBadge() or drawProgress()).

favoritos.setIcon()

/* Change favicon on tab change */
document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'visible') {
    document.title = 'Hello again! 😀';
    favoritos.setIcon('./on-visible.png')
  } else {
    document.title = 'I miss you! 😭';
    favoritos.setIcon('./on-visible.png')
  }
})

/* Change favicon on theme change */
window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (event) => {
  const newColorScheme = event.matches ? "dark" : "light";
  if (newColorScheme === 'dark') {
    favoritos.setIcon('./dark-favicon.png')
  } else {
    favoritos.setIcon('./light-favicon.png')
  }
});

Simply draws a new favicon.

favoritos.reset()

favoritos.reset();

Resets the library to its original state. Draws your default favicon.