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!

alt="GitHub Actions">

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 👀

$3

Installation 🚀

$3

#### npm
``shell script
$ npm install favoritos --save
`

#### yarn
`shell script
$ yarn add favoritos
`

$3

Add script right before closing tag

`html

or

`

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

`html









`

How to use 🤔

$3

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

const favoritos = new Favoritos({
icon: {
// Your options
},
badge: {
// Your options
},
debug: {
// Your options
},
});
`

Option B: Using CommonJS:
`js
const Favoritos = require('favoritos');

const favoritos = new Favoritos({
icon: {
// Your options
},
badge: {
// Your options
},
debug: {
// Your options
},
});
`

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

$3

#### 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()

`js
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()

`js
/ 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()

`js
/ 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()

`js
/ 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()

`js
/ 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()

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

`html

``

License 📄

$3

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!