grunt-favicons

Generates all known types and sizes icons from PNG image. Uses ImageMagick.

Input: square logo in png. You can also keep near the source files with resolution prefix e.g. source.16x16.png.

Output:

• favicon.ico (16x16, 32x32, 48x48) — desktop browsers, address bar, tabs, safari reading list, non-retina iPhone, windows 7+ taskbar, windows desktop;
• favicon.png (64x64) — modern browsers;
• apple-touch-icon.png (57x57) — iPhone non-retina, Android 2.1+;
• apple-touch-icon-60x60.png (60x60) — iPhone iOS7+;
• apple-touch-icon-72x72.png (72x72) — iPad non-retina;
• apple-touch-icon-76x76.png (76x76) — iPad non-retina iOS 7;
• apple-touch-icon-114x114.png (114x114) — iPhone retina, iOS 6 and lower;
• apple-touch-icon-120x120.png (120x120) — iPhone retina, iOS 7 and higher;
• apple-touch-icon-144x144.png (144x144) — iPad retina;
• apple-touch-icon-152x152.png (152x152) — iPad retina iOS 7;
• windows-tile-144x144.png (144x144) — Windows 8 tile;
• coast-icon-228x228.png (228x228) - Coast browser;
• firefox-icon-16x16.png (16x16) - Firefox on Android / Windows;
• firefox-icon-30x30.png (30x30) - Firefox OS;
• firefox-icon-32x32.png (32x32) - Firefox on Android / Windows;
• firefox-icon-48x48.png (48x48) - Firefox on Android / Windows;
• firefox-icon-60x60.png (60x60) - Firefox OS;
• firefox-icon-64x64.png (64x64) - Firefox on Android / Windows;
• firefox-icon-90x90.png (90x90) - Firefox OS;
• firefox-icon-120x120.png (120x120) - Firefox OS;
• firefox-icon-128x128.png (128x128) - Firefox on Android / Windows;
• firefox-icon-256x256.png (256x256) - Firefox on Android / Windows;
• homescreen-192x192.png (192x192) - Android Homescreen.

Adds changes to html file.

Getting Started

This plugin requires Grunt ~0.4.1 and ImageMagick.

Installing ImageMagick:

on Mac:

brew install imagemagick

on Linux:

apt-get install imagemagick

On Windows:

cinst imagemagick.app

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-favicons --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-favicons');

The "favicons" task

Overview

In your project's Gruntfile, add a section named favicons to the data object passed into grunt.initConfig().

grunt.initConfig({
  favicons: {
    options: {
      // Task-specific options go here.
    },
    your_target: {
      // Target-specific file lists and/or options go here.
    },
  },
})

Options

options.html

Type: String Default value: ''

Path to HTML you want to add links to icons.

options.truncateHTML

Type: Boolean Default value: false

Truncate the HTML file before adding links.

options.HTMLPrefix

Type: String Default value: ''

The path to the folder that contains the icons.

options.apple

Type: Boolean Default value: true

Generate apple icons.

options.regular

Type: Boolean Default value: true

Generate regular icons.

options.trueColor

Type: Boolean Default value: false

Use true color favicon.ico or 256 сolor. True color are larger.

options.sharp

Type: Float Default value: 0

Adaptively sharpen pixels. Increase effect near edges. 0 — disable.

options.precomposed

Type: Boolean Default value: true

When is false Safari on iOS < 7 add any effects to the icon.

options.appleTouchBackgroundColor

Type: String Default value: auto Values: auto|none|#COLOR

iOS icon can't be transparent. It needs background. If option set to auto color is selected automatically. none leaves transparency.

options.appleTouchPadding

Type: Integer Default value: 15

Padding in iOS icons. In percents.

options.windowsTile

Type: Boolean Default value: true

Add Windows 8 tile icon.

options.coast

Type: Boolean Default value: false

Add 228x228 icon for Coast browser.

options.tileBlackWhite

Type: Boolean Default value: true

Make white-only icon on Windows 8 tile.

options.tileColor

Type: String Default value: auto Values: auto|none|#COLOR

Background color for Windows 8 tile. If option set to auto color is selected automatically. none leaves transparency.

options.firefox

Type: Boolean Default value: false

Add icons for Firefox OS and Firefox on Android and Windows.

options.firefoxManifest

Type: String Default value: ''

Path to Firefox manifest you want to add links to icons.

options.firefoxRound

Type: Boolean Default value: false

Make Firefox OS icons rounded.

options.androidHomescreen

Type: Boolean Default value: false

Make Android Homescreen app icon.

options.indent

Type: String Default value: \t

String value for the indentation to be used for each link in the resulting HTML. Defaults to a tab character.

Low resolution

If you reduce the image to 16x16, it will blured. To avoid this, you can put near source image the prefixes. For example: source image called logo.png. If you put nearly logo.16x16.png then it will be used.

options.getLowResolutionImagePath

Type: Function Default value:

getLowResolutionImagePath: function (srcFilePath, size) {
    var extname = path.extname(srcFilePath);
    return path.join(path.dirname(srcFilePath), path.basename(srcFilePath, extname) + '.' + size + extname);
}

Change low resolution image path (default template of naming).

Usage Examples

Default Options

In this example, the default options are used to create favicon.ico, favicon.png, apple touch icons and windows 8 tile.

grunt.initConfig({
  favicons: {
    options: {},
    icons: {
      src: 'src/logo.png',
      dest: 'build/images'
    }
  },
})

Custom Options

grunt.initConfig({
  favicons: {
    options: {
      trueColor: true,
      precomposed: true,
      appleTouchBackgroundColor: "#e2b2c2",
      coast: true,
      windowsTile: true,
      tileBlackWhite: false,
      tileColor: "auto",
      html: 'build/out/index.html',
      HTMLPrefix: "/images/icons/"
    },
    icons: {
      src: 'src/logo.png',
      dest: 'build/images/icons'
    }
  },
})

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Feedback

Author: Vladimir Perekladov

Website: gleero.com

E-mail: gleero@gmail.com

Big thanks for contributing:

• ro-ka
• kfiku
• debugwand
• gausie
• alaz

Release History

2014-04-18 v0.6.4

• #28 Add Android Homescreen app icon.

2014-04-01 v0.6.3

• #21 Add sharp option for sharping icons.

2014-04-01 v0.6.2

• #24 Apple and regular favicons are now optional.

2014-03-05 v0.6.1

• Improved HTML tags clearing.

2013-12-19 v0.6.0

• #14 Add Firefox icon 120x120;
• #17 Append 70x70, 150x150 and 310x310 for MS tiles;
• Append Apple touch icon 60x60 for iOS 7;
• HTML link sizes order;
• All Apple touch icons contain;
• Linebreaks in HTML;
• #16, #15.

2013-12-11 v0.5.1

• Small bugfix (#12, #13).

2013-11-30 v0.5.0

• Add iOS icons padding;
• Support rounded Firefox OS icons.

2013-11-26 v0.4.0

• Small bugfix;
• #4 Supports php-tags in HTMLPrefix;
• #5 The task on startup removes all possible icons tags from html;
• #8 Firefox OS and Firefox for Android and Windows.

2013-10-11 v0.3.2

• #3 If destination folder does not exist, create it and continue.

2013-10-02 v0.3.0

• Add 76x76 for iPad non-retina iOS 7;
• Add 152x152 for iPad retina iOS 7;
• Disable non-precomposed icons for iOS 7 (is no longer supported).

2013-09-09 v0.2.0

• Add source image prefix;
• 228х228 Coast browser support;
• Readme.md fix.