iconizr v0.2.3

iconizr

iconizr is a Node.js module that reads a folder of SVG images and creates a CSS icon kit out of them, including:

• cleaned versions of the original SVG icons (optional),
• a single compact SVG icon sprite,
• optimized single PNG icons (optional),
• an optimized combined PNG icon sprite,
• corresponding CSS stylesheets in customizable formats (e.g. CSS, Sass, LESS, Stylus etc.),
• an HTML fragment including some JavaScript for asynchronously loading the most appropriate stylesheet flavour (depending on the client)
• and a couple of HTML preview documents (depending on the options you specified) for previewing and testing the different stylesheets (optional).

The stylesheets are rendered using Mustache templates, so you can control which output formats are generated (and how they are structured). For each of them, a set of several stylesheets are created, differing in the way the icons are served to clients:

• SVG single image icons (optional),
• SVG data URIs,
• SVG sprite references,
• PNG single image icons (optional),
• PNG data URIs and
• PNG sprite references.

Installation & usage

To install iconizr, run

npm install iconizr -g

on the command line.

Usage

The iconizr module exposes only one method, createIconKit(). Use it like this:

var Iconizr			    = require('iconizr'),
var options				= {
	
	// svg-sprite inferred options
	render				: {
		css				: false,
		scss			: 'sass/output/directory/',
		less			: {
			template	: 'path/to/less/mustache/template.less',
			dest		: '/absolute/path/to/dest/file'
		}
	},
	// ...
	
	// iconizr specific options
	quantize			: true,
	level				: 5
	/* Further configuration options, see below ... */
},
callback				= function(err, results) { /*
	If no error occurs, `results` will be a JSON object like this one:
	
	{
	   success			: true,		// Overall success
	   length			: 3,		// Total number of files written
	   files			: {			// Files along with their file size in bytes
	      '/path/to/your/cwd/css/output/directory/svg/sprite.svg'	: 436823,
	      '/path/to/your/cwd/css/output/directory/sprite.css'		: 1821,
	      '/path/to/your/cwd/sass/output/directory/_sprite.scss'	: 2197
	   },
	   options          : {         // refined configuration options, see above 
           // ...
	   },
	   data             : {         // Mustache template variables, see below
	       // ...
	   }
	}
	
*/};
Iconizr.createIconKit('path/with/svg/images', 'css/output/directory', options, callback);

The createIconKit() method will refuse to run if you don't pass exactly four arguments:

1. A path to be used as the input directory containing the SVG images for sprite creation. A relative path refers to the current working directory.
2. A main / default output directory, used for creating the stylesheet resources (CSS / Sass / LESS / Stylus etc. if activated and not specified otherwise; see the svg-sprite rendering options) and serving as a base for the sprite subdirectory given by spritedir see (svg-sprite configuration options). A relative path refers to the current working directory.
3. An object with configuration options (for both svg-sprite and iconizr specific). None of these options is mandatory, so you may pass an empty object {} here.
4. A callback to be run when the sprite creation has finished (with or without error).

Configuration

Options inferred from svg-sprite

iconizr is built on top of svg-sprite, which is a Node.js module for SVG sprite generation. All of svg-sprite's configuration options apply for iconizr as well. For a complete reference please see the svg-sprite documentation.

In particular, iconizr's rendering configuration and output format behaviour is identical to svg-sprite, so please have a look there for further reference.

Options for iconizr

Custom output formats & inline SVG embedding

The output rendering of iconizr is based on Mustache templates, which enables full customization of the generated results. You can even introduce completely new output formats. For details please see the svg-sprite documentation.

Also, you may use iconizr to create an inline SVG sprite that can be embedded directly into your HTML documents. Please see the svg-sprite documentation for details.

Other versions

Besides this Node.js module there are several different versions of iconizr:

• A Grunt plugin wrapping around this module.
• A PHP command line version (that in fact is the "original" one, but compared to the Node.js / Grunt branch it's a little outdated at the moment ...).
• The online service at iconizr.com that's based on the aforementioned PHP version (you can use it for creating CSS icon kits without the need of a local installation).
• Finally, Haithem Bel Haj published a Grunt plugin that's also based on the PHP version. I never tried this one myself, though.

Release History

v0.2.3

• Added concurrent task limit (#11)
• Updated dependencies (#9)
• Added support for JS-only loader fragment (#10)

v0.2.2

• Added a Stylus output template (#5)
• Added the variables config option (grunt-iconizr #13)

v0.2.1

• Fixed invalid background-position style in Sass / LESS templates (#4)

v0.2.0

• Switched to mustache.js for extended function support
• Fixed full disabling of output rendering (#2)
• Don't crash with empty input directory (#3)
• Fixed bug with the SVG sprite not used by the Sass & LESS output types (grunt-iconizr issue #6)
• Added new HTML output format for rendering an inline SVG HTML implementation (#1)
• Added new SVG output format for rendering an inline SVG sprite (#1)
• Documentation corrections

v0.1.0

• Initial release

Contributors

• Ralf Hortt

Legal

Copyright © 2014 Joschi Kuphal joschi@kuphal.net / @jkphl

iconizr is licensed under the terms of the MIT license.

The contained example SVG icons are part of the Tango Icon Library and belong to the Public Domain.