- Skip to main content
- Skip to "About this site"

# Favicon

Questions or comments?

## Purpose

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

## Use when

- Adding a mobile favicon to a web page.
- Dynamically updating the favicon of a web page.

## 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:
  2014-08-04