This file is part of the documentation of svg-sprite — a free low-level Node.js module that takes a bunch of SVG files, optimizes them and creates SVG sprites of several types. The package is hosted on GitHub.
The svg-sprite main configuration is provided to the constructor as an Object with the following structure:
{
dest: <String>, // Main output directory
log: <String|Logger>, // Logging verbosity or custom logger
shape: <Object>, // SVG shape configuration
svg: <Object>, // Sprite SVG options
variables: <Object>, // Custom templating variables
mode: <Object> // Output mode configurations
}All of these properties are optional so in fact, even an empty object {} is a valid configuration for svg-sprite. What follows is a complete reference of all available configuration settings. For getting off the ground quickly, you may also use the online configurator & kickstarter, which lets you create a custom configuration in seconds.
- Main output directory
- Logging
- SVG shape configuration
- Sprite SVG options
- Custom templating variables
- Output modes
| Property | Type | Default | Description |
|---|---|---|---|
dest |
String | . |
Main output directory which is used for resolving relative paths. Although svg-sprite doesn't write any files itself, it does need this setting in order to correctly layout the resulting file and directory structures. |
| Property | Type | Default | Description |
|---|---|---|---|
log |
String|Logger | svg-sprite uses winston for logging, but output is turned off by default. To activate and use the pre-configured console logger, you need to pass the desired log level ('info', 'verbose' or 'debug'). Alternatively, you can pass your own custom winston.Logger instance (which needs to handle at least these three log levels). Falsy values like "", false or null will disable logging. |
The shape property holds all settings affecting the SVG shapes of the sprite:
shape: {
id: { // SVG shape ID related options
separator: '--', // Separator for directory name traversal
generator: function() { /*...*/ }, // SVG shape ID generator callback
pseudo: '~', // File name separator for shape states (e.g. ':hover')
whitespace: '_' // Whitespace replacement for shape IDs
},
dimension: { // Dimension related options
maxWidth: 2000, // Max. shape width
maxHeight: 2000, // Max. shape height
precision: 2, // Floating point precision
attributes: false, // Width and height attributes on embedded shapes
},
spacing: { // Spacing related options
padding: 0, // Padding around all shapes
box: 'content' // Padding strategy (similar to CSS `box-sizing`)
},
transform: ['svgo'], // List of transformations / optimizations
sort: function() { /*...*/ }, // SVG shape sorting callback
meta: null, // Path to YAML file with meta / accessibility data
align: null, // Path to YAML file with extended alignment data
dest: null // Output directory for optimized intermediate SVG shapes
}| Property | Type | Default | Description |
|---|---|---|---|
shape.id.separator |
String | "--" |
Separator for traversing a directory structure into a shape ID. If empty, no directory traversal will happen and only the file name part (without the parent directory names) will be considered for the shape ID. |
shape.id.generator |
Function|String | See desc. | Callback for translating the local part of a shape's file name into a shape ID. The callback's signature is function(name, file) { /* ... */ return id; }, where name is the relative path of the source file within the base directory and file the original vinyl file object. By default, the file extension ".svg" is stripped off the name value and directory structures are traversed using the id.separator as replacement for the directory separator. You may also provide a template string (e.g. "icon-%s"), in which case the placeholder "%s" gets substituted with the traversed local file name. If the string doesn't contain any placeholder, it is used as a prefix to the local file name. |
shape.id.pseudo |
String | "~" |
String separator for pseudo CSS classes in file names. Example: my-icon.svg and my-icon~hover.svg for an icon with a regular and a :hover state. |
shape.id.whitespace |
String | "_" |
Replacement string for whitespace characters in file names during shape ID generation. Example: By default, My Custom Icon.svg will result in the shape ID my_custom_icon. |
| Property | Type | Default | Description |
|---|---|---|---|
shape.dimension.maxWidth |
Integer | 2000 |
Maximum shape width in pixels |
shape.dimension.maxHeight |
Integer | 2000 |
Maximum shape height in pixels |
shape.dimension.precision |
Integer | 2 |
Precision (number of decimal places) for dimension calculations |
shape.dimension.attributes |
Boolean | false |
Whether to add width and height attributes to embedded shapes («defs» and «stack» mode only) |
| Property | Type | Default | Description |
|---|---|---|---|
shape.spacing.padding |
Integer|Array | 0 |
Padding around shape. May be a single pixel value (which is then applied to all four edges) or an Array of Integers with a length between 1 and 4 (same syntax as for CSS padding) |
shape.spacing.box |
String | "content" |
Box sizing strategy, similar to CSS. When set to "content", the shape.spacing.padding values will get applied to the outside of each shape, effectively increasing the shape's bounding box. When set to "padding", the content plus the given spacing.padding values will stay within the dimension contraints shape.dimension.max* (they are the bounding box' maxima). When set to "icon", the shape.dimension.max* values are used as fixed dimensions for the bounding box around each shape. The shapes get either up- or downscaled proportionally to fit this bounding box (including shape.spacing.padding), resulting in all equally sized and distributed shape tiles (best fit for a set of same size icons). |
The shape.transform array holds a list of transformations that are applied — in order — to each of the SVG shapes before they get combined into the sprite. The list defaults to ['svgo']. The items of the shape.transform list might be of type String or Object.
If a shape.transform item is of type String, it's a shorthand and refers to a pre-defined transformation with the transformation's default configuration. At the time of this writing, the only supported pre-defined transformation is svgo:
// SVGO transformation with default configuration
{
shape: {
transform: ['svgo']
/* ... */
}
}If you don't want to use a pre-defined transformation or its default configuration, you need to use the Object notation. Each of the shorthands can be expanded like this:
// Equivalent transformation to ['svgo']
{
shape: {
transform: [
{svgo: {}}
]
/* ... */
}
}In this case, the list item's first object key is used as the transformation name. Depending on its value type,
- a pre-defined shape transformation with custom configuration or
- a custom callback
will be called.
To call a pre-defined transformation with custom configuration options, use its name as the transformation name and provide an object which will get merged over the default configuration:
// SVGO transformation with custom plugin configuration
{
shape: {
transform: [{
svgo: {
plugins: [{
name: 'preset-default',
params: {
overrides: {
convertShapeToPath: false,
moveGroupAttrsToElems: false
}
}
}]
}
}]
/* ... */
}
}To use a custom callback for transforming a shape's SVG, pass a function with the following signature:
// SVGO transformation with custom plugin configuration
{
shape: {
transform: [
{custom:
/**
* Custom callback transformation
*
* @param {SVGShape} shape SVG shape object
* @param {SVGSpriter} spriter SVG spriter
* @param {Function} callback Callback
* @return {void}
*/
(shape, sprite, callback) => {
/* ... */
callback(null);
}
}
]
/* ... */
}
}The transformation name ("custom" in this case) is of no significance. Please see lib/svg-sprite/shape.js to learn about what you can do with the shape object.
| Property | Type | Default | Description |
|---|---|---|---|
shape.sort |
Function | Callback for sorting the list of shapes. The callback's signature is function(shape1, shape2) { /* ... */ return order; }. It gets passed two shape objects and is expected to return an integer with 0 meaning both shapes are equal in their position, 1 meaning the first shape should follow the second one, and -1 the other way round. The default callback simply compares the shapes' id values and returns them in alphabetical order, but you may as well implement your own ordering logic. |
|
shape.meta |
String | Path to a YAML file with meta data to be injected into the SVG shapes. | |
shape.align |
String | Path to a YAML file with extended alignment settings for sprites with "vertical" or "horizontal" layout. |
|
shape.dest |
String | Implicit way of calling .getShapes() during sprite compilation. If given, the result of subsequent .compile() calls will carry an additional shapes property, listing the intermediate SVG files as an Array of vinyl files. The value will be used as the destination directory for the files (relative to the main output directory if not absolute anyway). |
The svg object holds common options that apply to each SVG sprite created. The common options might be overridden by mode configurations (see below).
| Property | Type | Default | Description |
|---|---|---|---|
svg.xmlDeclaration |
Boolean|String | true |
Output an XML declaration at the very beginning of each compiled sprite. If you provide a non-empty string here, it will be used one-to-one as declaration (e.g. <?xml version="1.0" encoding="utf-8"?>). If you set this to true, svg-sprite will look at the registered shapes for an XML declaration and use the first one it can find. |
svg.doctypeDeclaration |
Boolean|String | true |
Include a <DOCTYPE> declaration in each compiled sprite. If you provide a non-empty string here, it will be used one-to-one as declaration (e.g. <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1 Basic//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11-basic.dtd">). If you set this to true, svg-sprite will look at the registered shapes for a DOCTYPE declaration and use the first one it can find. |
svg.namespaceIDs |
Boolean | true |
In order to avoid ID clashes, the default behavior is to namespace all IDs in the source SVGs before compiling them into a sprite. Each ID is prepended with a unique string. In some situations, it might be desirable to disable ID namespacing, e.g. when you want to script the resulting sprite. Just set svg.namespaceIDs to false then and be aware that you might also want to disable SVGO's ID minification (shape.transform.svgo.plugins.params.overrides: {cleanupIDs: false}). |
svg.namespaceIDPrefix |
String | Under some circumstances, the automatically generated ID namespaces might interfere with external scripts (e.g. see this issue for a problem detected with Google Analytics). In these situations it might be helpful to prefix all IDs with a custom prefix set with this option. | |
svg.namespaceClassnames |
Boolean | true |
In order to avoid CSS class name ambiguities, the default behavior is to namespace CSS class names in the source SVGs before compiling them into a sprite. Each class name is prepended with a unique string. Disable this option to keep the class names untouched. |
svg.dimensionAttributes |
Boolean | true |
If truthy, width and height attributes will be set on the sprite's <svg> element (where applicable). |
svg.rootAttributes |
Object | Shorthand for applying custom attributes to the outermost <svg> element. Please be aware that certain attributes (e.g. viewBox) will be calculated dynamically and override custom rootAttributes in any case. |
|
svg.precision |
Integer | Floating point precision for CSS positioning values (defaults to -1 meaning highest possible precision). |
|
svg.transform |
Function|Array | Callback (or list of callbacks) that will be applied to the resulting SVG sprites as global post-processing transformation. |
The svg.transform option can be used to post-process and customize the SVG sprites. You may specify a callback (or a list of callbacks) with the following signature:
// Custom global post-processing transformation
{
svg: {
transform: [
/**
* Custom sprite SVG transformation
*
* @param {String} svg Sprite SVG
* @return {String} Processed SVG
*/
svg => {
/* ... */
return svg;
},
/* ... */
]
}
}The callbacks are processed synchronously and in the given order. Each one is passed to the sprite's SVG source as its first (and only) argument and is expected to return the modified SVG source after transformation. It's completely up to what you do with the SVG source, just don't forget to return it in the end. You may e.g. run some regex or even full-blown DOM operations on the SVG contents (svg-sprite depends on xmldom, so you may require a parser instance const DOMParser = require('@xmldom/xmldom').DOMParser; /* ... */ within your callback ...).
The top-level variables object lets you define global variables that are passed to all Mustache templating processes across all output modes. You may either use scalar values or callbacks (see here for details on Mustache callbacks). Example:
{
variables: {
now: Number(new Date()),
png() {
return (sprite, render) => render(sprite).split('.svg').join('.png');
}
}
}Please refer to the templating guide to learn about the builtin functions provided by svg-sprite as well as the sprite and shape variables available during rendering.
svg-sprite currently supports 5 different output modes:
cssviewdefssymbolstack
Please see the configuration sections below to learn a little about their natures and differences.
Each of them produces its own specific files and has its individual configuration. You may enable and configure several modes in parallel so that svg-sprite renders them in one run, saving the redundant SVG optimization overhead. Enabling a specific mode is as easy as adding a like-named key to the mode property, using either the default configuration (by using true as the value) or a custom settings object:
// Activate the «css» mode with default configuration
{
mode: {
css: true
}
}
// Equivalent: Provide an empty configuration object
{
mode: {
css: {}
}
}It is also possible to configure the same output mode multiple times, each time with a different configuration. In that case, use a custom key for the configuration object and give it the special mode property telling svg-sprite which output mode to use with this configuration:
// Multiple sprites of the same output mode
{
mode: {
sprite1: {
mode: 'css' // Sprite with «css» mode
},
sprite2: {
mode: 'css' // Another sprite with «css» mode
}
}
}Many mode properties are common between all sprite types (sometimes their default values differ from type to type, however). The placeholder "<mode>" is used as a substitute for one of "css", "view", "defs", "symbol" or "stack". Please replace it consequently.
| Property | Type | Default | Description |
|---|---|---|---|
mode.<mode>.dest |
String | "<mode>" |
Base directory for sprite and CSS file output. If not absolute, the path will be resolved using the main output directory (see global dest option). |
mode.<mode>.prefix |
String | ".svg-%s" |
Used for prefixing the shape ID during CSS selector construction. If the value is empty, no prefix will be used. The prefix may contain the placeholder "%s" (e.g. ".svg %s-svg"), which will then get replaced by the shape ID. Please be aware that "%" is a special character in this context and that you'll have to escape it by another percent sign ("%%") in case you want to output it to your stylesheets (e.g. for a Sass placeholder selector). |
mode.<mode>.dimensions |
String|Boolean | "-dims" |
A non-empty string value will trigger the creation of additional CSS rules specifying the dimensions of each shape in the sprite. The string will be used as suffix to mode.<mode>.prefix during CSS selector construction and may contain the placeholder "%s", which will get replaced by the value of mode.<mode>.prefix. A boolean true will cause the dimensions to be included directly into each shape's CSS rule (only available for «css» and «view» sprites). |
mode.<mode>.sprite |
String | "svg/sprite.<mode>.svg" |
SVG sprite path and file name, relative to the mode.<mode>.dest directory (see above). You may omit the file extension, in which case it will be set to ".svg" automatically. |
mode.<mode>.bust |
Boolean | true|false |
Add a content based hash to the name of the sprite file so that clients reliably reload the sprite when its content changes («cache busting»). Defaults to false except for «css» and «view» sprites. |
mode.<mode>.render |
Object of Rendering configs | {} |
Collection of stylesheet rendering configurations. The keys are used as file extensions as well as file return keys. At present, there are default templates for the file extensions css (CSS), scss (Sass), less (Less) and styl (Stylus), which all reside in the directory tmpl/css. Example: {css: true, scss: {dest: '_sprite.scss'}} |
mode.<mode>.example |
Rendering config | false |
Enabling this will trigger the creation of an HTML document demoing the usage of the sprite. Please see below for details on rendering configurations. |
mode.<mode>.example.template |
String | "tmpl/<mode>/sprite.html" |
HTML document Mustache template |
mode.<mode>.example.dest |
String | "sprite.<mode>.html" |
HTML document destination |
The «css» mode creates a single SVG file by combining the original shapes as nested <svg> elements with individual horizontal and vertical offsets. CSS resources can be created that provide rules for using the shapes as background images of HTML elements (known as CSS spriting).
The «view» mode is an extension to the «css» mode and shares all its features. The generated SVG sprite differs only in additionally created <view> elements for each shape in the sprite. By using the views' IDs as fragment identifiers when linking to the sprite, modern browsers will show the referenced shapes only, thus making the sprite useful for foreground images as well. Please see this article by Chris Coyier for further explanation of the technique.
In addition to the common mode properties, «css» and «view» sprites have these specific options:
| Property | Type | Default | Description |
|---|---|---|---|
mode.<mode>.layout |
String | "packed" |
The arrangement of the shapes within the sprite. Might be "vertical", "horizontal", "diagonal" or "packed" (with the latter being the most compact type). It depends on your project which layout is best for you. |
mode.<mode>.common |
String | If given and not empty, this will be the selector name of a CSS rule commonly specifying the background-image and background-repeat properties for all the shapes in the sprite (thus saving some bytes by not unnecessarily repeating them for each shape) |
|
mode.<mode>.mixin |
String | If given and not empty, a mixin with this name will be added to supporting output formats (e.g. Sass, LESS, Stylus), specifying the background-image and background-repeat properties for all the shapes in the sprite. You may use it for creating custom CSS within @media rules. The mixin acts much like the common rule. In fact, you can even combine the two — if both are enabled, the common rule will use the mixin internally. |
The «defs» mode creates a single SVG file combining the original shapes as children of a global <defs> element. You can then <use> the shapes with either document-internal references (<svg viewBox="0 0 100 100"><use xlink:href="#internal-id"/></svg> while having the SVG sprite embedded inline into the very same document) or as an external SVG spritemap (<svg viewBox="0 0 100 100"><use xlink:href="http://example.com/sprite.svg#fragment-id"/></svg>). Please see this article by Chris Coyier for further explanation of the technique.
The «symbol» mode behaves pretty much like the «defs» mode except it's using <symbol> elements to combine the original shapes into a sprite. Again, you can <use> the shapes with either document-internal references (<svg><use xlink:href="#internal-id"/></svg> while having the SVG sprite embedded inline into the very same document) or as an external SVG spritemap (<svg><use xlink:href="http://example.com/sprite.svg#fragment-id"/></svg>). Please see this article by Chris Coyier for further explanation of the <symbol> technique. Compared to the defs mode, one of the main benefits is that you don't have to provide the viewBox attribute on every <use> element which makes it a lot easier.
In addition to the common mode properties, «defs» and «symbol» sprites have one extra option:
| Property | Type | Default | Description |
|---|---|---|---|
mode.<mode>.inline |
Boolean | false |
If you want to embed the sprite into your HTML source, you will want to set this to true in order to prevent the creation of SVG namespace declarations and to set some other attributes for effectively hiding the library sprite. |
The «stack» mode creates a single SVG file by combining the original shapes as nested <svg> elements. Instead of spreading the shapes using individual horizontal and/or vertical offsets, the stack contains a small CSS portion that hides all the shapes by default. Only the active shape as determined by the :target pseudo selector will be visible. For this technique to work, the client will have to support SVG fragment identifiers or use a polyfill like fixsvgstack.jquery.js. Please see this post by simurai for a further explanation of SVG stacks.
In addition to the common mode properties, «stack» sprites have one extra option:
| Property | Type | Default | Description |
|---|---|---|---|
mode.<mode>.rootviewbox |
Boolean | true |
If you want to disable rendering of the root elements viewBox attribute, you will want to set this to false. This way for example you can have svg sprites in multiple aspect ratios. |
svg-sprite uses Mustache templates for creating certain output formats. Typically, the generation of these files is optional and you have to switch on the rendering process:
- For creating a CSS resource alongside your sprite, you will have to enable/configure at least one output format via the
mode.<mode>.renderoption. - For creating an example HTML document demoing the use of your sprite, you will have to enable/configure it using
mode.<mode>.example.
In both cases, you'll have to use a rendering configuration to tell svg-sprite which template it should use and where the result file should be targeted to. Let's take a look at the mode.<mode>.example option. To enable the demo HTML document with the default template and destination, simply set the value to true:
{
mode: {
css: {
example: true
}
}
}This is equivalent to:
{
mode: {
css: {
example: {}
}
}
}Use the subkey template for configuring the rendering template and dest for specifying the output file destination:
{
mode: {
css: {
render: {
css: {
template: 'path/to/template.html', // relative to current working directory
dest: 'path/to/demo.html' // relative to current output directory
}
}
}
}
}To disable the rendering without removing the whole structure, simply set the value to something falsy:
{
mode: {
css: {
example: false
}
}
}