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

or

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

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

Badge options

Debug options

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

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

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!