{"id":13685654,"url":"https://github.com/svg-sprite/svg-sprite","last_synced_at":"2025-05-14T11:08:13.116Z","repository":{"id":13887359,"uuid":"16585561","full_name":"svg-sprite/svg-sprite","owner":"svg-sprite","description":"SVG sprites \u0026 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.)","archived":false,"fork":false,"pushed_at":"2025-05-01T22:52:11.000Z","size":12391,"stargazers_count":1959,"open_issues_count":55,"forks_count":255,"subscribers_count":26,"default_branch":"main","last_synced_at":"2025-05-07T10:52:35.700Z","etag":null,"topics":["css","html","less","mustache","sass","sprite","svg","svgo"],"latest_commit_sha":null,"homepage":"https://github.com/svg-sprite/svg-sprite","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/svg-sprite.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2014-02-06T16:33:22.000Z","updated_at":"2025-05-03T08:52:10.000Z","dependencies_parsed_at":"2024-05-01T23:42:57.795Z","dependency_job_id":"7a7796bf-797c-4ac8-b6f1-247a5021d785","html_url":"https://github.com/svg-sprite/svg-sprite","commit_stats":{"total_commits":865,"total_committers":58,"mean_commits":"14.913793103448276","dds":0.638150289017341,"last_synced_commit":"1466fdda01cdfcb14a3da6d3d8a1bb3c75148c33"},"previous_names":["jkphl/svg-sprite"],"tags_count":99,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svg-sprite%2Fsvg-sprite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svg-sprite%2Fsvg-sprite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svg-sprite%2Fsvg-sprite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svg-sprite%2Fsvg-sprite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/svg-sprite","download_url":"https://codeload.github.com/svg-sprite/svg-sprite/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253457961,"owners_count":21911768,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["css","html","less","mustache","sass","sprite","svg","svgo"],"created_at":"2024-08-02T14:00:55.304Z","updated_at":"2025-05-14T11:08:13.067Z","avatar_url":"https://github.com/svg-sprite.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# svg-sprite\n\n[![npm version][npm-image]][npm-url] [![Build Status][ci-image]][ci-url] [![Coverage Status][coveralls-image]][coveralls-url] [![npm downloads][npm-downloads]][npm-url]\n\nsvg-sprite is a low-level [Node.js](https://nodejs.org/) module that **takes a bunch of [SVG](https://www.w3.org/TR/SVG/) files**, optimizes them and bakes them into **SVG sprites** of several types:\n\n* Traditional [CSS sprites](https://en.wikipedia.org/wiki/Sprite_(computer_graphics)#Sprites_by_CSS) for use as background images,\n* CSS sprites with **pre-defined `\u003cview\u003e` elements**, useful for foreground images as well,\n* inline sprites using the **`\u003cdefs\u003e` element**,\n* inline sprites using the **`\u003csymbol\u003e` element**\n* and [SVG stacks](https://simurai.com/blog/2012/04/02/svg-stacks).\n\nIt comes with a set of [Mustache](https://mustache.github.io/) templates for creating stylesheets in good ol' [CSS](https://www.w3.org/Style/CSS/) or one of the major **pre-processor formats** ([Sass](https://sass-lang.com/), [Less](https://lesscss.org/) and [Stylus](https://stylus-lang.com/)). Tweaking the templates or even adding your own **custom output format** is really easy, just as switching on the generation of an **HTML example document** along with your sprite.\n\nFor an up-to-date list of browsers supporting [SVG in general](https://caniuse.com/svg) respectively [SVG fragment identifiers](https://caniuse.com/svg-fragment) in particular (required for `\u003cdefs\u003e` and `\u003csymbol\u003e` sprites as well as SVG stacks) please refer to [caniuse.com](https://caniuse.com/).\n\n## Grunt, Gulp \u0026 Co.\n\nBeing a low-level library with support for [Node.js streams](https://github.com/substack/stream-handbook), *svg-sprite* doesn't take on the part of accessing the file system (i.e. reading the source SVGs from and writing the sprites and CSS files to disk). If you don't want to take care of this stuff yourself, you might rather have a look at the available wrappers for **Grunt** ([grunt-svg-sprite](https://github.com/svg-sprite/grunt-svg-sprite)) and **Gulp** ([gulp-svg-sprite](https://github.com/svg-sprite/gulp-svg-sprite)). *svg-sprite* is also the foundation of the **[iconizr](https://github.com/jkphl/node-iconizr)** project, which serves high-quality SVG based **CSS icon kits with PNG fallbacks**.\n\n\n## Table of contents\n\n* [Installation](#installation)\n* [Getting started](#getting-started)\n  * [Usage pattern](#usage-pattern)\n  * [Standard API](docs/api.md)\n  * [Grunt \u0026 Gulp wrappers](docs/grunt-gulp.md)\n* [Configuration basics](#configuration-basics)\n  * [General configuration options](#general-configuration-options)\n  * [Output modes](#output-modes)\n    * [Common mode properties](#common-mode-properties)\n    * [Basic examples](#basic-examples)\n  * [Output destinations](#output-destinations)\n    * [Pre-processor formats and the sprite location](#pre-processor-formats-and-the-sprite-location)\n  * [Full configuration documentation](docs/configuration.md)\n  * [Online configurator \u0026 project kickstarter](https://svg-sprite.github.io/svg-sprite/)\n* [Advanced techniques](#advanced-techniques)\n  * [Meta data injection](docs/meta-data.md)\n  * [Aligning and duplicating shapes](docs/shape-alignment.md)\n  * [Tweaking and adding output formats](docs/templating.md)\n* [Command line usage](docs/command-line.md)\n* [Known problems / To-do](#known-problems--to-do)\n* [Changelog](CHANGELOG.md)\n* [Legal](#legal)\n\n\n## Installation\n\nTo install *svg-sprite* globally, run:\n\n```bash\nnpm install svg-sprite -g\n```\n\n\n## Getting started\n\nCrafting a sprite with *svg-sprite* typically follows these steps:\n\n1. You [create an instance of the SVGSpriter](docs/api.md#svgspriter-config-), passing a main configuration object to the constructor.\n2. You [register a couple of SVG source files](docs/api.md#svgspriteraddfile--name-svg-) for processing.\n3. You [trigger the compilation process](docs/api.md#svgspritercompile-config--callback-) and receive the generated files (sprite, CSS, example documents etc.).\n\nThe procedure is the very same for all supported sprite types («modes»).\n\n\n### Usage pattern\n\n```js\nconst fs = require('fs');\nconst path = require('path');\nconst SVGSpriter = require('svg-sprite');\n\n// Create spriter instance (see below for `config` examples)\nconst spriter = new SVGSpriter(config);\n\n// Add SVG source files — the manual way ...\nspriter.add('assets/svg-1.svg', null, fs.readFileSync('assets/svg-1.svg', 'utf-8'));\nspriter.add('assets/svg-2.svg', null, fs.readFileSync('assets/svg-2.svg', 'utf-8'));\n/* ... */\n\n// Compile the sprite\nspriter.compile((error, result) =\u003e {\n  /* Write `result` files to disk (or do whatever with them ...) */\n  for (const mode of Object.values(result)) {\n    for (const resource of Object.values(mode)) {\n      fs.mkdirSync(path.dirname(resource.path), { recursive: true });\n      fs.writeFileSync(resource.path, resource.contents);\n    }\n  }\n});\n\n// Or compile the sprite async\nconst { result } = await spriter.compileAsync();\n/* Write `result` files to disk (or do whatever with them ...) */\nfor (const mode of Object.values(result)) {\n  for (const resource of Object.values(mode)) {\n    fs.mkdirSync(path.dirname(resource.path), { recursive: true });\n    fs.writeFileSync(resource.path, resource.contents);\n  }\n}\n\n```\n\nAs you can see, big parts of the above are dealing with disk I/O. In this regard, you can make your life easier by [using the Grunt or Gulp wrappers](docs/grunt-gulp.md) instead of the [standard API](docs/api.md).\n\n\n## Configuration basics\n\nOf course you noticed the `config` variable passed to the constructor in the above example. This is *svg-sprite*'s **main configuration** — an `Object` with the following properties:\n\n```js\n{\n  dest: \u003cString\u003e, // Main output directory\n  log: \u003cString|Logger\u003e, // Logging verbosity or custom logger\n  shape: \u003cObject\u003e, // SVG shape configuration\n  svg: \u003cObject\u003e, // Common SVG options\n  variables: \u003cObject\u003e, // Custom templating variables\n  mode: \u003cObject\u003e // Output mode configurations\n}\n```\n\nIf you don't provide a configuration object altogether, *svg-sprite* uses built-in defaults for these properties, so in fact, they are all optional. However, you will need to enable at least one **output mode** (`mode` property) to get reasonable results (i.e. a sprite of some type).\n\n\n### General configuration options\n\nMany configuration properties (all except `mode`) apply to all sprites created by the same spriter instance. The default values are:\n\n```js\n// Common svg-sprite config options and their default values\nconst config = {\n  dest: '.', // Main output directory\n  log: null, // Logging verbosity (default: no logging)\n  shape: { // SVG shape related options\n    id: { // SVG shape ID related options\n      separator: '--', // Separator for directory name traversal\n      generator: function () { /*...*/ }, // SVG shape ID generator callback\n      pseudo: '~' // File name separator for shape states (e.g. ':hover')\n    },\n    dimension: {// Dimension related options\n      maxWidth: 2000, // Max. shape width\n      maxHeight: 2000, // Max. shape height\n      precision: 2, // Floating point precision\n      attributes: false, // Width and height attributes on embedded shapes\n    },\n    spacing: { // Spacing related options\n      padding: 0, // Padding around all shapes\n      box: 'content' // Padding strategy (similar to CSS `box-sizing`)\n    },\n    transform: ['svgo'], // List of transformations / optimizations\n    meta: null, // Path to YAML file with meta / accessibility data\n    align: null, // Path to YAML file with extended alignment data\n    dest: null // Output directory for optimized intermediate SVG shapes\n  },\n  svg: { // General options for created SVG files\n    xmlDeclaration: true, // Add XML declaration to SVG sprite\n    doctypeDeclaration: true, // Add DOCTYPE declaration to SVG sprite\n    namespaceIDs: true, // Add namespace token to all IDs in SVG shapes\n    namespaceIDPrefix: '', // Add a prefix to the automatically generated namespaceIDs\n    namespaceClassnames: true, // Add namespace token to all CSS class names in SVG shapes\n    dimensionAttributes: true // Width and height attributes on the sprite\n  },\n  variables: {} // Custom Mustache templating variables and functions\n}\n```\n\nPlease refer to the [configuration documentation](docs/configuration.md) for details.\n\n\n### Output modes\n\nAt the moment, *svg-sprite* supports **five different output modes** (i.e. sprite types), each of them has its own characteristics and use cases. It's up to you to decide which sprite type is the best choice for your project. The `mode` option controls which sprite types are created. You may enable more than one output mode at a time — *svg-sprite* will happily create several sprites in parallel.\n\nTo enable the creation of a specific sprite type with default values, simply set the appropriate `mode` property to `true`:\n\n```js\nconst config = {\n  mode: {\n    css: true, // Create a «css» sprite\n    view: true, // Create a «view» sprite\n    defs: true, // Create a «defs» sprite\n    symbol: true, // Create a «symbol» sprite\n    stack: true // Create a «stack» sprite\n  }\n}\n```\n\nTo further configure a sprite, pass in an object with configuration options:\n\n```js\n// «symbol» sprite with CSS stylesheet resource\nconst config = {\n  mode: {\n    css: {\n      // Configuration for the «css» sprite\n      // ...\n    }\n  }\n}\n```\n\n\n#### Common mode properties\n\nMany `mode` properties are shared between the different sprite types, but there are also type specific options. Please refer to the [configuration documentation](docs/configuration.md) for a complete list of settings.\n\n```js\n// Common mode properties\nconst config = {\n  mode: {\n    \u003cmode\u003e: {\n      dest: \"\u003cmode\u003e\", // Mode specific output directory\n      prefix: \"svg-%s\", // Prefix for CSS selectors\n      dimensions: \"-dims\", // Suffix for dimension CSS selectors\n      sprite: \"svg/sprite.\u003cmode\u003e.svg\", // Sprite path and name\n      bust: true || false, // Cache busting (mode dependent default value)\n      render: { // Stylesheet rendering definitions\n        /* -------------------------------------------\n        css: false, // CSS stylesheet options\n        scss: false, // Sass stylesheet options\n        less: false, // LESS stylesheet options\n        styl: false, // Stylus stylesheet options\n        \u003ccustom\u003e: ... // Custom stylesheet options\n        -------------------------------------------  */\n      },\n      example: false // Create an HTML example document\n    }\n  }\n}\n```\n\n\n#### Basic examples\n\n\n##### A) Standalone sprite\n\nForeground image **sprite with `\u003csymbol\u003e` elements** (for being `\u003cuse\u003e`d in your HTML source):\n\n```js\n// «symbol» sprite with CSS stylesheet resource\nconst config = {\n  mode: {\n    symbol: {    // Create a «symbol» sprite\n      inline: true // Prepare for inline embedding\n    }\n  }\n}\n```\n\n\n##### B) CSS sprite with Sass resource\n\nTraditional **CSS sprite** with a **Sass stylesheet**:\n\n```js\n// «css» sprite with Sass stylesheet resource\nconst config = {\n  mode: {\n    css: { // Create a «css» sprite\n      render: {\n        scss: true // Render a Sass stylesheet\n      }\n    }\n  }\n}\n```\n\n\n##### C) Multiple sprites\n\n**`\u003cdefs\u003e` sprite**, **`\u003csymbol\u003e` sprite** and an **SVG stack** all at once:\n\n```js\n// «defs», «symbol» and «stack» sprites in parallel\nconst config = {\n  mode: {\n    defs: true,\n    symbol: true,\n    stack: true\n  }\n}\n```\n\n\n##### D) No sprite at all\n\n`mode`-less run, returning the **optimized SVG shapes only**:\n\n```js\n// Just optimize source SVG files, create no sprite\nconst config = {\n  shape: {\n    dest: 'path/to/out/dir'\n  }\n}\n```\n\n\n### Output destinations\n\nDepending on your particular configuration, *svg-sprite* creates a lot of files that partly refer to each other. Several configuration options are controlling the exact location of each file, and you are well advised to spend a moment understanding how they interrelate with each other.\n\nRelative destination paths refer to their ancestors as shown in the following scheme, with the current working directory being the ultimate base.\n\n```text\n    Destination option           Default         Comment\n---------------------------------------------------------------------------------------------\ncwd $   \u003cdest\u003e/                .           Main output directory\n      \u003cmode.css.dest\u003e/           css           «css» base directory\n        \u003cmode.css.sprite\u003e        svg/sprite.css.svg  Sprite location\n        \u003cmode.css.render.css.dest\u003e   sprite.css      CSS stylesheet location\n        \u003cmode.css.render.scss.dest\u003e  sprite.scss       Sass stylesheet location\n        ...\n      \u003cmode.view\u003e/             view          «view» base directory\n        ...\n```\n\nBy default, stylesheet resources are generated directly into the respective **mode's base directory**.\n\n\u003e \"Oh wait! Didn't you say that *svg-sprite* doesn't access the file system? So why do you need output directories at all?\" — Well, good point. *svg-sprite* uses [vinyl](https://github.com/gulpjs/vinyl) file objects to pass along virtual resources and to specify where they **are intended to be located**. This is especially important for relative file paths (e.g. the path of an SVG sprite as used by a CSS stylesheet).\n\n\n#### Pre-processor formats and the sprite location\n\nSpecial care needs to be taken when you create a **CSS sprite** («css» or «view» mode) along with a stylesheet in one of the **pre-processor formats** (Sass, LESS, Stylus, etc.). In this case, calculating the correct relative SVG sprite path as used by the stylesheets can become tricky, as your (future) plain CSS compilation doesn't necessarily lie side by side with the pre-processor file. *svg-sprite* doesn't know anything about your pre-processor workflow, so it might have to estimate the location of the CSS file:\n\n1. If you **truly configured CSS output** in addition to the pre-processor format, *svg-sprite* uses your custom `mode.\u003cmode\u003e.render.css.dest` as the CSS stylesheet location.\n2. If you just **enabled CSS output** by setting `mode.\u003cmode\u003e.render.css` to `true`, the default value applies, which is `mode.\u003cmode\u003e.dest / \"sprite.css\"`.\n3. The same holds true when you **don't enable CSS output** at all. *svg-sprite* then simply assumes that the CSS file will be created where the defaults would put it, which is again `mode.\u003cmode\u003e.dest / \"sprite.css\"`.\n\nSo even if you don't enable plain CSS output explicitly, please make sure to set `mode.\u003cmode\u003e.dest` to **where your final CSS file is intended to be**.\n\n\n### Full configuration documentation\n\nThe complete configuration documentation including all options [can be found here](docs/configuration.md).\n\n\n### Online configurator \u0026 project kickstarter\n\nTo get you quickly off the ground, I made a simple [online configurator](https://svg-sprite.github.io/svg-sprite/) that lets you create a custom *svg-sprite* configuration in seconds. You may download the results as plain JSON, Node.js project, Gruntfile, or Gulpfile. Please visit the configurator at \u003chttps://svg-sprite.github.io/svg-sprite/\u003e.\n\n\n## Advanced techniques\n\n\n### Meta data injection\n\nIn order to improve accessibility, *svg-sprite* can read meta data from a YAML file and inject `\u003ctitle\u003e` and `\u003cdescription\u003e` elements into your SVGs. Please refer to the [meta data injection guide](docs/meta-data.md) for details.\n\n\n### Aligning and duplicating shapes\n\nFor CSS sprites using a `\"horizontal\"` or `\"vertical\"` layout it is sometimes desirable to align the shapes within the sprite. With the help of an external YAML file, *svg-sprite* can not only [control the alignment](docs/shape-alignment.md#aligning-and-duplicating-shapes) for each individual shape but also [create displaced copies](docs/shape-alignment.md#creating-displaced-shape-copies) of them without significantly increasing the sprite's file size.\n\n\n### Tweaking and adding output formats\n\n*svg-sprite* uses [Mustache](https://mustache.github.io/) templates for rendering the various CSS resources. This makes it very easy to tailor the generated CSS / Sass / LESS / Stylus resources to your needs or add completely new output formats. Please refer to the [templating guide](docs/templating.md) to learn about the details.\n\n\n## Command line usage\n\n*svg-sprite* comes with a pretty feature complete command line version. A typical example could look like this:\n\n```bash\nsvg-sprite --css --css-render-css --css-example --dest=out assets/*.svg\n```\n\nPlease refer to the [CLI guide](docs/command-line.md) for further details.\n\n\n## Known problems / To-do\n\n* SVGO does not minify element IDs when there are `\u003cstyle\u003e` or `\u003cscript\u003e` elements contained in the file\n\n\n## Changelog\n\nPlease refer to the [GitHub releases](https://github.com/svg-sprite/svg-sprite/releases) for a complete release history.\n\n\n## Legal\n\nCopyright © 2018 Joschi Kuphal \u003cjoschi@kuphal.net\u003e / [@jkphl](https://twitter.com/jkphl). *svg-sprite* is licensed under the terms of the [MIT license](LICENSE). The contained example SVG icons are part of the [Tango Icon Library](http://tango.freedesktop.org/Tango_Icon_Library) and belong to the Public Domain.\n\n\n[npm-url]: https://www.npmjs.com/package/svg-sprite\n[npm-image]: https://img.shields.io/npm/v/svg-sprite?logo=npm\u0026logoColor=fff\n[npm-downloads]: https://img.shields.io/npm/dm/svg-sprite\n\n[ci-url]: https://github.com/svg-sprite/svg-sprite/actions/workflows/test.yml?query=branch%3Amain\n[ci-image]: https://img.shields.io/github/actions/workflow/status/svg-sprite/svg-sprite/test.yml?branch=main\u0026label=CI\u0026logo=github\n\n[coveralls-url]: https://coveralls.io/github/svg-sprite/svg-sprite?branch=main\n[coveralls-image]: https://img.shields.io/coveralls/github/svg-sprite/svg-sprite/main?logo=coveralls\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsvg-sprite%2Fsvg-sprite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsvg-sprite%2Fsvg-sprite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsvg-sprite%2Fsvg-sprite/lists"}