Favoritos

Favoritos is a JavaScript plugin that adds some HTML5 canvas magic to your favicon. With just a wee bit of code, we can make some really cool effects.

⭐️ Star me on GitHub — it helps!

Key Features • Demo • Installation • How To Use • Browsers support • License • Contributing

Key Features ✨

Small. ~ 2.78KB (minified and gzipped). Size Limit controls the size.
No dependencies.
Friendly and flexible configuration
Easy to use
Typescript support
SSR friendly

Demo 👀

DEMO

Installation 🚀

Using package managers

npm

$ npm install favoritos --save

yarn

$ yarn add favoritos

via CDN

Add script right before closing </body> tag

<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>

How to use 🤔

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.

Browsers support 🌎

IE / Edge	Firefox	Chrome	Safari	iOS Safari	Opera	Yandex
IE11*, Edge 12+	40+	42+	10.1+	10.3+	29+	15.6+

* – For IE11 you need to install Object.assign polyfill. Also IE11 cannot render base64 icons, so the setIcon method only works there.

If you want to send a polyfill only to browsers that need it, there's a handy service called Polyfill.io which does just that, it offers a wide array of polyfills.

Here's an example of using polyfill.io to polyfill only the Object.assign feature, so if we put this right before closing </body> tag of index.html and Favoritos script, Polyfill.io will read the user agent and use that information to determine if the browser requires a polyfill for the feature or features listed. Since I'm using Chrome it will send back an empty response since my browser doesn't need it, pretty slick.

<script src="https://polyfill.io/v3/polyfill.min.js?features=Object.assign"></script>

License 📄

MIT

Contributing 🎉

Found a bug? Missing a specific feature? Your contributions are always welcome! Please have a look at the contribution guidelines first.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

_{Alexey Istomin}
🚇 💻 🤔

This project follows the all-contributors specification. Contributions of any kind welcome!

webistomin/favoritos