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-196x196.png (196x196) - 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.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.

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.