SVG + PNG icon kit generator — A low-level Node.js module that creates a CSS icon kit from a bunch of SVG files, serving them as SVG / PNG sprites or embedded data URIs along with suitable CSS / Sass / LESS / Stylus etc. stylesheet resources and a JavaScript loader for easy integration into your HTML documents
This version of node-iconizr is still based on an outdated version of svg-sprite. Links to the svg-sprite manual have been adapted. An updated version of node-iconizr will be available soon, supporting all the shiny new features. Thanks for your patience! <3
iconizr is a Node.js module that reads a folder of SVG images and creates a CSS icon kit out of them, including:
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:
To install iconizr, run
npm install iconizr -g
on the command line.
The iconizr module exposes only one method, createIconKit()
. Use it like this:
var Iconizr = require('iconizr'),
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:
spritedir
see (svg-sprite configuration options). A relative path refers to the current working directory.{}
here.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.
Option | Description |
---|---|
render | Rendering configuration (output formats like CSS, Sass, LESS, Stylus, HTML with inline SVG, etc.) |
variables | Custom Mustache rendering variables [{} ] |
spritedir | Sprite subdirectory name ["svg" ] |
sprite | Sprite file name ["sprite" ] |
prefix | CSS selector prefix ["svg" ] |
common | Common CSS selector for all images [empty] |
maxwidth | Maximum single image width [1000 ] |
maxheight | Maximum single image height [1000 ] |
padding | Transparent padding around the single images (in pixel) [0 ] |
layout | Image arrangement within the sprite ("vertical" , "horizontal" or "diagonal" ) ["vertical" ] |
pseudo | Character sequence for denoting CSS pseudo classes ["~" ] |
dims | Render image dimensions as separate CSS rules [false ] |
keep | Keep intermediate SVG files (inside the sprite subdirectory) [false ] |
recursive | Recursive scan of the input directory for SVG files [false ] |
verbose | Output verbose progress information (0-3) [0 ] |
cleanwith | Module to be used for SVG cleaning. Currently "scour" or "svgo" ["svgo" ] |
cleanconfig | Configuration options for the cleaning module [{} ] |
In particular, iconizr's rendering configuration and output format behaviour is identical to svg-sprite, so please have a look there for further reference.
Property | Type | Description |
---|---|---|
quantize |
Boolean | Whether to quantize PNG images (reduce to 8-bit depth) using pngquant . The quantized images are only used if they are smaller in file size than their the originals (and this is not necessarily the case for all PNG files). Quantization may also impact the visual image quality, so please make sure to compare the result to the original images. Defaults to false . |
level |
Number (0-11) | This is the optimization level for PNG files. It has to lie between 0 and 11 (inclusive) and defaults to 4, with 0 meaning "no optimization", 1 meaning "fast & rough" and 11 meaning "slow & high quality". Setting this to a high value may result in a very long processing time. Defaults to 3 . |
embed |
String | If given, iconizr will use this value as path prefix to embed the stylesheets into your HTML documents (used for the JavaScript loader fragment). By default, the path segment between the current working directory and the main output directory will be used as a root-relative embed path (i.e. giving path/to/css as output directory will result in the loader fragment expecting the CSS stylesheets to lie at /path/to/css/<stylesheet-flavour>.css ). You may specify a period . here to make the embed path relative to your HTML document (i.e. ./<stylesheet-flavour>.css ), or use any other relative path (e.g. ../resources for the embed path ../resources/<stylesheet-flavour>.css ). |
svg |
Number | This is the maximum length a SVG data URI may have. If only one icon exceeds this threshold, all data URIs of this icon set will be changed to external SVG sprite references. Defaults to 1048576 (1MB), minimum is 1024 (1kB). |
png |
Number | This is the maximum length a PNG data URI may have. If only one icon exceeds this threshold, all data URIs of this icon set will be changed to external PNG sprite references. Defaults to 32768 (32KB = Internet Explorer 8 limit), minimum is 1024 (1kB). |
preview |
String | If given and not empty, a set of preview HTML documents will be rendered that can be used for previewing and testing the icon kit. The given value will be used as directory path relative to the main output directory, whereas the main preview document will be named after your CSS file name ({render: {css: '...'}} ) or the prefix option (in case no CSS files are generated). |
loader |
Object | With this option you get some control about the format and destination of the JavaScript loader fragment: loader.type may be "html" (for an HTML loader fragment; this is the default) or "js" (for a JavaScript file only). The Boolean loader.minify controls whether the loader script will get uglyfied (defaults to TRUE ). Finally, loader.dest is the path (relative to the main output directory) where the loader resource will be written to (defaulting to "." ). |
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.
Besides this Node.js module there are several different versions of iconizr:
variables
config option (grunt-iconizr #13)background-position
style in Sass / LESS templates (#4)Copyright © 2014 Joschi Kuphal [email protected] / @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.