favoritos
TypeScript icon, indicating that this package has built-in type declarations

1.1.0 • Public • Published

Favoritos

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!

GitHub Actions codecoverage CodeFactor GitHub issues GitHub last commit npm type definitions npm bundle size

npm downloads jsdeliver contributors

Key FeaturesDemoInstallationHow To UseBrowsers supportLicenseContributing

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
IE / Edge
Firefox
Firefox
Chrome
Chrome
Safari
Safari
iOS Safari
iOS Safari
Opera
Opera
Yandex
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!

Package Sidebar

Install

npm i favoritos

Weekly Downloads

20

Version

1.1.0

License

MIT

Unpacked Size

118 kB

Total Files

67

Last publish

Collaborators

  • webistomin