is a Node.js module that reads a folder of SVG images, optimizes them and creates an SVG sprite along with suitable stylesheet resources (e.g. CSS, Sass or LESS). Additional formats may easily be added by providing appropriate Mustache templates.
On a personal note: This is my first ever Node.js module, so please be forgiving in case of errors (and drop me a line instead of dropping the module altogether — I'd really appreciate that). svg-sprite is closely related to another project of mine — iconizr — which exists in several versions (Node.js module, Grunt plugin, PHP version and online service). That said, you will find most of the configuration options being relevant for iconizr as well.
To install svg-sprite, run
npm install svg-sprite -g
on the command line.
You may use svg-sprite as a command line tool. Type svg-sprite -h to get all the available options:
Usage: svg-sprite [options] [command]
Commands:
*
Convert the SVG files in the given directory. If omitted, the current working directory is used.
Options:
-h, --help Output usage information
-V, --version Output the version number
-o, --out <output-directory> Default output directory for stylesheets and the sprite subdirectory
-r, --render <render-config> Rendering configuration [{css: true}]
--spritedir <sprite-directory> Sprite subdirectory name [svg]
--sprite <sprite-filename> Sprite file name [sprite]
-p, --prefix <selector-prefix> CSS selector prefix [svg]
--common <common-selector> Common CSS selector for all images []
--maxwidth <max-width> Maximum single image width [1000]
--maxheight <max-height> Maximum single image height [1000]
--padding <padding> Transparent padding around the single images (in pixel) [0]
--layout <layout> Sprite images arrangement ("vertical", "horizontal" or "diagonal") [vertical]
--pseudo <pseudo-separator> Character sequence for denoting CSS pseudo classes [~]
-d, --dims Render image dimensions as separate CSS rules [false]
-k, --keep Keep intermediate SVG files (inside the sprite subdirectory) [false]
--recursive Recursively scan for SVG files in subdirectories
-v, --verbose Output verbose progress information (0-3) [0]
--cleanwith <clean-module> Module to be used for SVG cleaning. Currently "scour" or "svgo" [svgo]
--cleanconfig <clean-configuration> JSON-serialized configuration options for the cleaning module [{}]
-q, --quiet Don't print any status messages
Please see below to learn more about the options and their values.
This command reads all SVG files from the current directory and uses the subdirectory sprite to create an SVG sprite and CSS file into it:
$ svg-sprite --out sprite
$ svg-sprite -co sprite
This one creates an SVG sprite and it's CSS along with a Sass file at sprite/sass/_sprite.scss:
$ svg-sprite --out sprite --render '{"scss":{"dest":"sprite/sass/_sprite"}}'
This last one uses the subdirectory ./svg as input directory, adds additional image size CSS rules, optimizes the SVG images using SVGO and doesn't discard them in the end:
$ svg-sprite --keep --dims --out sprite --cleanwith svgo ./svg
$ svg-sprite -kdo sprite --cleanwith svgo ./svg
The svg-sprite module exposes only one method, createSprite(). Use it like this:
var SVGSprite = require('svg-sprite'),
var options = {
render : {
css : false,
scss : 'sass/output/directory/',
less : {
template : 'path/to/less/mustache/template.less',
dest : '/absolute/path/to/dest/file'
}
}
/* 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
}
}
*/};
SVGSprite.createSprite('path/with/svg/images', 'css/output/directory', options, callback);
The createSprite() method will refuse to run if you don't pass exactly four arguments:
spritedir (see below). A relative path refers to the current working directory.{} here.These are the options you may pass as the createSprite() method's third argument:
| Property | Type | Description |
|---|---|---|
render |
String (JSON) | You may provide a configuration object that controls which output files and formats are generated and which Mustache rendering templates are used for the generation. It defaults to {css: true}, which means that a CSS file with the default name will be generated to the default location. This option is available since v0.1.0; prior to that, the now deprecated options css, sass, sassout, less and lessout were used for controlling the rendering behaviour. See below for an explanation of all rendering options. |
spritedir |
Directory path | Directory relative to the main output directory where the SVG sprite will be created. Defaults to 'svg'. Starting with version v0.1.0 you may also provide an empty string or . to avoid the creation of a subdirectory altogether. |
sprite |
String | Filename of the SVG sprite (preceding the .svg extension). Defaults to 'sprite'. |
prefix |
String | Prefix for all CSS rules (all output formats). Defaults to 'svg' (results in .svg-* CSS selectors) |
common |
String | If given and not empty, it will be used for creating a CSS rule that commonly defines the background-image and background-repeat properties for all the sprite images (thus saving some bytes by not unnecessarily repeating these properties for each sprite image) |
maxwidth |
Integer | Maximum width of single SVG images. Will be downscaled if necessary. Defaults to 1000. |
maxheight |
Integer | Maximum height of single SVG images. Will be downscaled if necessary. Defaults to 1000. |
padding |
Integer | Padding around the single SVG images in the sprite. Defaults to 0. |
layout |
String | Method of arranging the single SVG images in the sprite. Can be "vertical", "horizontal" or "diagonal", defaults to vertical. |
pseudo |
String | Char to separate CSS pseudo classes in file names. See the iconizr documentation for details. Defaults to ~. |
dims |
Boolean | If present and equal to true, additional CSS rules will be rendered (all output formats) that set the dimensions of the single sprite images. You can use these CSS rules for sizing your elements appropriately. In general, the suffix -dims will be used in conjunction with the regular CSS selector for the image, but please have a look at the generated CSS file as well as the iconizr documentation for some special rules regarding CSS pseudo classes. |
keep |
Boolean | If present and equal to true, the single optimized intermediate SVG images used for creating the sprite will not be discarded, but kept in the spritedir as well. |
recursive |
Boolean | If present and equal to true, the input directory will be recursively scanned for SVG files in subdirectories. The directory names will be used for constructing the sprite image CSS class names, concatenated by hyphens. |
verbose |
Integer | Set this to a value > 0 to get some output. Defaults to 0. |
cleanwith |
String | Select the module used for optimizing the single SVG images. Currently, the Node.js modules svg-cleaner (loosely based on Scour) and SVGO are supported, so use either scour or svgo for this option. Set it to FALSE or NULL to skip the SVG optimization altogether. Defaults to svgo (starting with version v0.1.1). ATTENTION: Currently Scour is not supported (until an updated release gets available) |
cleanconfig |
String (JSON) | You may provide a configuration object that is passed to the SVG optimizer (currently, only SVGO supports this). It defaults to {plugins: [{moveGroupAttrsToElems: false}]}. When used on the command line, provide a valid JSON encoded string here. |
Starting with version v0.1.0, the output rendering of svg-sprite is based on Mustache templates. Compared to the earlier approach, template based rendering gives you way more flexiblity: Not only you can produce almost any (text based) output format, but also wrap the results with custom code or completely rearrange it's structure.
At the moment, svg-sprite comes with predefined templates for CSS, Sass (SCSS) and LESS, but you can easily overwrite them or add custom templates for different formats. The render option controls,
You have to provide a JavaScript object as the value for render. Each property of this object controls one output format. The property names mainly serve as keys but also define the default file extensions in case they are not specified by the destination file names (see below). A very simple render object could look like this (in fact, this is the default rendering configuration; for an explanation see below):
{
css: true
}
Besides serving as a unique key, the property name css also indicates the default file extension for output files generated by this format. The value true indicates that the default values should apply for both the rendering template as well as the output filename. That said, the above render object is equivalent to any of these:
{
css : {}
}
// is equivalent to
{
css : '<output-directory>/sprite.css' // default output file for CSS
}
// is equivalent to
{
css: {
dest : '<output-directory>/sprite.css' // default output file for CSS
}
}
// is equivalent to
{
css: {
template : '/path/to/svg-sprite/tmpl/sprite.css', // default template for CSS
dest : '<output-directory>/sprite.css' // default output file for CSS
}
}
You can find the three provided standard templates sprite.css, sprite.scss and sprite.less in the subdirectory tmpl of your svg-sprite installation. By default, output files will be named just like their corresponding template files.
If a template path is given, it must point to an existing template file — otherwise the conversion process will exit. The dest property can be provided as an absolute or relative path, as directory or file name, with or without file extension. The missing parts will be automatically expanded using default values. See the following equivalents to understand the mechanism:
// A relative path
{
css : 'path/to/template.css'
}
// expands to an absolute
{
css : '/path/to/svg-sprite/<output-directory>/path/to/template.css'
}
// A missing file extension
{
scss : '/path/to/svg-sprite/path/to/template'
}
// expands to the template's file extension, whereas the template is determined
// by the overall format key (if not explicitly specified via `template`)
{
scss : '/path/to/svg-sprite/path/to/template.scss' // default template: sprite.scss
}
// A missing file name
{
less : {
template : '/path/to/custom.less',
dest : '/path/to/svg-sprite/path/to/directory/'
}
}
// is also derived from the template
{
less : {
template : '/path/to/custom.less',
dest : '/path/to/svg-sprite/path/to/directory/custom.less' // default template: sprite.less
}
}
// An empty destination
{
css : ''
}
// expands to an absolute one with all default values
{
css : '/path/to/svg-sprite/<output-directory>/sprite.css'
}
To disable a certain output format, set it's value to false or null:
{
// Disable CSS rendering
css : false,
// Activate Sass rendering
scss : 'sass/output/directory/',
// Activate LESS rendering with custom template
less : {
template : 'path/to/less/mustache/template.less',
dest : '/absolute/path/to/dest/file'
}
}
Introducing a custom output format — or overwriting one of the predefined ones — is really easy: Just put a valid Mustache template to a location of your liking and configure it like this (the expansion mechanisms described above apply here as well):
{
myformat : {
template : 'path/to/custom/mustache/template.abc',
dest : 'path/to/output/file.xyz'
}
}
The JavaScript hash piped into the template rendering process typically looks something like this:
{
// CSS class name for `common` sprite image properties (or FALSE if disabled)
"common": "icon",
// `Prefix` for all CSS rules
"prefix": "svg",
// Path to the generated SVG sprite, relative to the main output directory
"sprite": "svg/sprite.svg",
// Whether to render image dimension CSS rules
"dims": false,
// Padding around each sprite image (pixel)
"padding": 9,
// Overall sprite width (pixel)
"swidth": 50,
// Overall sprite height (pixel)
"sheight": 160,
// List of all sprite images
"svg": [
// Single sprite image configuration
{
// Sprite image name
"name": "weather-clear-night",
// List of CSS selector expressions for this sprite image
"selector": [
{
"expression": "svg-weather-clear-night",
"raw": "svg-weather-clear-night",
"first": true, // Indicating the first expression
"last": false
},
{
"expression": "svg-weather-clear-night\\:regular",
"raw": "svg-weather-clear-night:regular", // Unescaped expression version
"first": false,
"last": true // Indicating the last expression
}
],
// Sprite image width (pixel; excluding padding)
"width": 32,
// Sprite image height (pixel; excluding padding)
"height": 32,
// Horizontal offset of the image within the sprite (pixel; including padding; always 0 for vertical sprites)
"positionX": 0,
// Vertical offset of the image within the sprite (pixel; including padding; always 0 for horizontal sprites)
"positionY": 0,
// CSS background position values (including "px" unit if necessary)
"position": "0 0",
// Sprite image dimension configuration (if activated, otherwise FALSE)
"dimensions": {
// List of CSS selector expressions for this sprite image dimensions
"selector": [
{
"expression": "svg-weather-clear-night-dims",
"raw": "svg-weather-clear-night-dims",
"first": true, // Indicating the first expression
"last": true // Indicating the last expression
}
],
// Sprite image width (pixel; including padding)
"width": 50,
// Sprite image width (pixel; including padding)
"height": 50
}
}
/* Further sprite images */
]
}
Please read the Mustache manual to get familiar with the rendering mechanism.
In case you want to embed the SVG sprite into your HTML source and reference it via SVG fragment identifiers (<use xlink:href="...">), you will need to use a slightly different version of the SVG sprite (with the sprite images wrapped into a <defs> element). Starting with version 0.3.0, svg-sprite comes with an Inline sprite output template (tmpl/sprite.inline.svg) suitable for generating this embeddable sprite variant. You may trigger it's creation by using the inline.svg rendering configuration key:
// Create "<default-output-directory>/sprite.inline.svg"
{
'inline.svg' : true
}
// ... or create "<default-output-directory>/inline/sprite.svg"
{
'inline.svg' : {
template : 'tmpl/sprite.inline.svg',
dest : 'inline/sprite'
}
}
Also, to give you an idea of how to use the inline sprite, there's a new output template for rendering an HTML preview document that demonstrates some possible use cases. The html rendering configuration key triggers it's creation:
// Create "<default-output-directory>/sprite.html"
{
html : true
}
// ... or create "<default-output-directory>/custom/preview.html"
{
html : {
template : 'tmpl/sprite.html',
dest : 'custom/preview'
}
}
The preview document features both the use of document-internal SVG references (<use xlink:href="#internal-id"/>) as well as external SVG spritemaps (<use xlink:href="http://example.com/sprite.svg#fragment-id"/>) as described by Chris Coyier and others (including the polyfill SVG for Everybody for Internet Explorer 9-11).
<style> or <script> elements contained in the fileconsole.log() viewBox attribute (#10, thanks to @arminrosu)viewBox attribute for image dimension calculation (#9):regular pseudo-pseudo class:regular pseudo-pseudo class (#7)css, sass, sassout, less and lessout configuration options, added render insteadwidth and height config options from lib/svg-obj.js common optionCopyright © 2014 Joschi Kuphal joschi@kuphal.net / @jkphl
svg-sprite 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.