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 favoritos
Add script right before closing </body>
tag
<script src="https://unpkg.com/[email protected]/dist/favoritos.iife.js"></script>
or
<script src="https://cdn.jsdelivr.net/npm/[email protected]/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!