svg-sprite
Advanced tools
Takes a folder of SVG images and creates an SVG sprite along with suitable stylesheet resources (e.g. CSS, Sass, LESS or Stylus) out of them
The svg-sprite npm package is a powerful tool for creating SVG sprites. It allows you to combine multiple SVG files into a single file, which can then be used to optimize the delivery and performance of SVG assets in web applications. The package supports various modes of sprite generation, including symbol, stack, and CSS sprites, and provides a range of configuration options to customize the output.
Symbol Sprite Mode
This feature allows you to create a symbol sprite, which is a single SVG file containing multiple symbols. Each symbol can be referenced individually using the <use> element in your HTML.
const svgSprite = require('svg-sprite');
const config = {
mode: {
symbol: {
dest: 'out',
sprite: 'symbol-sprite.svg'
}
}
};
svgSprite(config).then(() => console.log('Symbol sprite created!'));CSS Sprite Mode
This feature allows you to create a CSS sprite, which is a single SVG file that can be used with CSS to display individual icons. The package can also generate the corresponding CSS file to use the sprite.
const svgSprite = require('svg-sprite');
const config = {
mode: {
css: {
dest: 'out',
sprite: 'css-sprite.svg',
render: {
css: true
}
}
}
};
svgSprite(config).then(() => console.log('CSS sprite created!'));Stack Sprite Mode
This feature allows you to create a stack sprite, which is a single SVG file containing multiple stacked SVG elements. Each element can be referenced individually using the <use> element in your HTML.
const svgSprite = require('svg-sprite');
const config = {
mode: {
stack: {
dest: 'out',
sprite: 'stack-sprite.svg'
}
}
};
svgSprite(config).then(() => console.log('Stack sprite created!'));svg-sprite-loader is a webpack loader that allows you to import SVG files as symbols in a sprite. It is similar to svg-sprite in that it helps optimize SVG delivery, but it is specifically designed to work with webpack, making it a good choice for projects that use webpack for module bundling.
gulp-svg-sprite is a Gulp plugin for creating SVG sprites. It offers similar functionality to svg-sprite but is designed to be used within a Gulp build process. This makes it a good option for projects that use Gulp for task automation.
svgstore is a simple tool for creating SVG sprites. It is less feature-rich compared to svg-sprite but provides a straightforward way to combine multiple SVG files into a single sprite. It is a good choice for projects that need a lightweight solution for SVG sprite generation.
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, LESS or Stylus). 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. Due to complexity issues, the variables option is not available for the CLI version.
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. |
variables | Object | You may use this option to pass additional custom variables to the Mustache rendering process. Be aware that there are a couple of reserved keys that are not available for custom variables (common, prefix, sprite, dims, padding, swidth, sheight, svg, date, invert, escape). You may also pass callback functions as variables (see here for further details). |
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), LESS and Stylus, 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 provided standard templates sprite.css, sprite.scss, sprite.less and sprite.styl 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",
// Sprite image height (pixel; excluding padding)
"height": 32,
// Sprite image width (pixel; excluding padding)
"width": 32,
// Last image of sprite
"last": false,
// 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
}
],
// 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
},
// Inline SVG image for being referenced by <use> elements
"data": "<svg width=\"48\" height=\"48\" id=\"weather-clear-night\" y=\"0\">...</svg>"
}
/* Further sprite images */
],
// Current date (RFC-1123)
"date": "Fri, 30 May 2014 20:04:18 GMT"
}
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 filevariables config option (grunt-iconizr #13)console.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.jscommon 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.
FAQs
SVG sprites & stacks galore — A low-level Node.js module that takes a bunch of SVG files, optimizes them and bakes them into SVG sprites of several types along with suitable stylesheet resources (e.g. CSS, Sass, LESS, Stylus, etc.)
The npm package svg-sprite receives a total of 138,874 weekly downloads. As such, svg-sprite popularity was classified as popular.
We found that svg-sprite demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.