Favicon

Looking for WET v3.1?

As of September 23, 2014, version 3.1 of the Web Experience Toolkit is no longer supported. The source code and documentation have been moved to the wet-boew-legacy repository.

Questions or comments?

Purpose

This plugin provides the ability to add and update a web page's favicon.

Use when

Working example

English example

French example

How to implement

Add a mobile favicon:

  1. Add a favicon to the web page using a link element: 
    <link href="favion.ico" rel="icon" type="image/x-icon">
  2. Optionally specify the mobile favion's filename, path, rel attribute and sizes attribute: 
    <link href="favion.ico" rel="icon" type="image/x-icon" 
	data-filename="my-mobile-favicon.ico" 
	data-path="/path/to/favicon/"
	data-rel="apple-touch-icon-precomposed"
	data-sizes="57x57">

Update an existing favicon's href attribute:

  1. Using JavaScript, get a reference to the favicon's link element: 
    var $favicon = $( "link[rel='icon']" );
  2. Trigger the icon.wb-favicon event on the favicon element: 
    $favicon.trigger( "icon.wb-favicon" );
    Note: the update of the favicon's href attribute will be based on its data-path and data-filename attributes.

Configuration options

All configuration options of the plugin are controlled with data attributes:

Option Description How to configure Values
data-filename Filename of the mobile favicon. It is appended to the favicon's path (specified by data-path). Set to the filename of the mobile favicon.
None (default):
If not specified, defaults to "favicon-mobile.png"
String (favicon filename):
Custom mobile favicon filename.
data-path Full path to the mobile favicon. Set to the full path of the mobile favicon.
None (default):
If not specified, defaults to the same path as the <link> icon
String (favicon path):
Custom mobile favicon path.
data-rel Favicon rel attribute. Set to the desired rel attribute value of the favicon.
None (default):
If not specified, defaults to "apple-touch-icon"
String (favicon rel attribute):
Custom mobile favicon rel attribute.
data-sizes Favicon sizes attribute. Set to the desired sizes attribute value of the favicon.
None (default):
If not specified, defaults to "57x57 72x72 114x114 144x144 150x150"
String (favicon sizes attribute):
Custom mobile favicon sizes attribute.

Events

Document the public events that can be used by implementers or developers.

Event Trigger What it does
wb-init.wb-favicon Triggered manually (e.g., $( "link[rel='icon']" ).trigger( "wb-init.wb-favicon" );). Initializes the plugin and creates a mobile favicon if it doesn't already exist. Note: the favicon plugin will be initialized automatically unless the link element is added after the page has already loaded.
wb-ready.wb-favicon (v4.0.5+) Triggered automatically after the Favicon plugin initializes. Used to identify when the Favicon plugin has initialized 
$( document ).on( "wb-ready.wb-favicon", "link[rel='icon']", function( event ) {
});
$( "link[rel='icon']" ).on( "wb-ready.wb-favicon", function( event ) {
});
wb-updated.wb-favicon (v4.0.5+) Triggered automatically after the favicon update has completed. Used to identify when the plugin has finished updating the favicon and to pass along what type of favicon was updated (mobile, icon). 
$( document ).on( "wb-updated.wb-favicon", "link[rel='icon']", function( event ) {
});
$( "link[rel='icon']" ).on( "wb-updated.wb-favicon", function( event ) {
});
mobile.wb-favicon Triggered manually and during plugin initialization (e.g., $( "link[rel='icon']" ).trigger( "mobile.wb-favicon" );). Adds or updates the mobile favicon on the web page. This will only update a mobile favicon that was added by the plugin.
icon.wb-favicon Triggered manually (e.g., $( "link[rel='icon']" ).trigger( "icon.wb-favicon" );). Updates the favicon's href attribute based on its data-filename and data-path attributes.
wb-ready.wb (v4.0.5+) Triggered automatically when WET has finished loading and executing. Used to identify when all WET plugins and polyfills have finished loading and executing. 
$( document ).on( "wb-ready.wb", function( event ) {
});

Source code

Favicon source code on GitHub

Date modified: