Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including @leo-burnett-melbourne/svg-mixer with all npm packages installed. Try it out:

var svgMixer = require("@leo-burnett-melbourne/svg-mixer")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

@leo-burnett-melbourne/svg-mixer v2.3.8

Library for generating and transforming SVG sprites in modern way

SVG Mixer

Library for generating and transforming SVG sprites in modern way.

Table of contents

Quick example

const mixer = require('svg-mixer');

  .then(result => console.log(result.content));

// Write sprite content on disk
mixer(['img/**/*.svg', '!img/raw/**'])
  .then(result => result.write('sprite.svg'));

// 'Stack' sprite
mixer('img/**/*.svg', { spriteType: 'stack' })
  .then(result => result.write('sprite.svg'));

// Classic sprite with empty canvas and <defs> section with symbols
// Useful for inlining directly in HTML markup and refer to images via <use xlink:href="#symbol-id" />
mixer('img/**/*.svg', { spriteConfig: { usages: false } })
  .then(result => result.write('sprite.svg'));


npm install svg-mixer




Type: string
Default: classic

Possible values:

  • classic (default). Images placed on canvas one after the other. Works perfect in all browsers including IE10+. If sprite embedded in CSS - requires some additional styles for background image positioning. postcss-svg-mixer can be used to generate such styles.
  • stack. SVG stacking technique - images placed one below the other and hidden by default. Target image becomes visible via CSS :target selector when referencing sprite, eg. sprite.svg#twitter. Doesn't work in Safari (both desktop and mobile) prior to 11.1 macOS and 11.3 iOS. Don't requires any styles when embedding.


Type: Object

Fine tune sprite output.

  • filename (default: 'sprite.svg'). Sprite file name.
  • attrs (default: {}). Additional sprite SVG attributes, eg. { class: 'my-sprite' }.
  • usages (default: true). Render images on sprite canvas or just place their symbols in <defs> section. It's useful to set false when sprite inlined directly to HTML markup and symbols are referenced via <use xlink:href="#symbol-id" />. Make sense only for classic sprite
  • spacing (default: 10). Spacing between symbols in pixels. Make sense only for classic sprite

Stack sprite also has following options:

  • usageClassName (default: sprite-symbol-usage). CSS classname of symbol to set. Needed to avoid possible conflicts between sprite and symbol styles.
  • styles (default: see stack-sprite). CSS to archive stack technique. Will be placed in <defs> section.


Type: function(path: string, query: string = '') => string

Function to generate <symbol id> attribute. By default file name without extension is used. Accepts 2 arguments: absolute path to file and optional query string.


Type: boolean
Default: false

Prettify sprite output.


Custom sprite implementation. See extending section.


Custom sprite symbol implementation. See extending section.


Main function

Main function accepts 2 arguments: glob pattern and config. Glob pattern could be string or array of strings. Relative/absolute path to file is also allowed:

mixer(['img/*.svg', '!img/raw/*.svg']); // all from img/, but not from img/raw/
mixer(['img/*.svg', 'path/to/file', '/absolute/path/to/file']);


Result is an object with content and filename fields, and write() method:

  content: string,
  filename: string,
  write(filepath: string) => Promise

The rest API docs will be ASAP. For now check TypeScript definitions and source :)


svg-mixer offers OOP-like extending mechanism - to write custom sprite or symbol transformation you'll need to extend a base class and override generate method, which returns promise resolved with postsvg.tree.

Example: add class="my-super-class" to each node in generated sprite.

const mixer = require('svg-mixer');

class MySprite extends mixer.Sprite {
  generate() {
    // Call parent `generate` method and then transform the tree
    return super.generate().then(svg => {
      svg.each(node => node.attrs.class = 'my-super-class');
      return svg;

mixer('img/*.svg', { spriteClass: MySprite });

As it possible to pass query params when adding image to sprite by addSymbolFromFile compiler method, it makes possible to process single file with different params in various ways (like webpack does).

Example: fill one image with different colors.

const mixer = require('svg-mixer');
const transform = require('posthtml-transform');

class MySymbol extends mixer.SpriteSymbol {
  generate() {
    const { query } = this.image;
    return super.generate().then(svg => transform(query)(svg));

const compiler = new mixer.Compiler({ symbolClass: MySymbol });
  .then(() => compiler.addSymbolFromFile('img.svg?fill=red'))
  .then(() => compiler.compile())
  .then(result => console.log(result.content));

The code above will generate sprite with 2 symbols - original image and filled with red color. In this example adding images and generating sprite performed manually, but when using svg-mixer adapters you'll need only to pass custom implementation to adapter config.



RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free