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.
Key Features • Demo • Installation • How To Use • Browsers support • License • Contributing
- Small. ~ 2.78KB (minified and gzipped). Size Limit controls the size.
- No dependencies.
- Friendly and flexible configuration
- Easy to use
- Typescript support
- SSR friendly
$ npm install favoritos --save$ yarn add favoritosAdd 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>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
},
});| 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. |
| 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 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. |
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.
 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>Found a bug? Missing a specific feature? Your contributions are always welcome! Please have a look at the contribution guidelines first.
Thanks goes to these wonderful people (emoji key):
 Alexey Istomin 🚇 💻 🤔 |
This project follows the all-contributors specification. Contributions of any kind welcome!