command-line.md

svg-sprite

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.

Command line usage

You may use svg-sprite as a command line tool. Type svg-sprite --help to get all the available options:

Usage: svg-sprite [options] files

Options:
  --version                      Show version number  [boolean]
  --help                         Display this help information  [boolean]
  -D, --dest                     Main output directory (base path)  [default: "."]
  -C, --config                   Path to external JSON config file
  -l, --log                      Logging verbosity ("info", "verbose" or "debug")
  --shape-id-separator           Separator for traversing a directory structure into a shape ID  [default: "--"]
  --shape-id-generator           ID generation callback [via CLI only template strings]  [default: "%s"]
  --shape-id-pseudo              Separator for CSS pseudo classes  [default: "~"]
  --shape-id-whitespace          Whitespace replacement string for shape IDs  [default: "_"]
  -w, --shape-dim-width          Maximum shape width in pixels  [default: 2000]
  -h, --shape-dim-height         Maximum shape height in pixels  [default: 2000]
  --shape-dim-precision          Precision (decimal places) for dimension calculations  [default: 2]
  --shape-dim-attributes         Whether to add width and height attributes to the shapes  [boolean] [default: false]
  -p, --shape-spacing-padding    Padding around shape (up to 4 x comma-separated)  [default: "0,0,0,0"]
  -b, --shape-spacing-box        Box sizing strategy ("content", "padding" or "icon")  [default: "content"]
  -m, --shape-meta               Path to YAML file with meta information
  -a, --shape-align              Path to YAML file with alignment information
  --ims, --shape-dest            Path to output directory for intermediate SVG files
  --shape-transform              Comma-separated list of predefined transformers (see docs)  [default: "svgo"]
  --shape-transform-*            External JSON config files for named transformers
  --svg-xmldecl                  Whether to include an XML declaration in SVG files  [boolean] [default: true]
  --svg-doctype                  Whether to include a doctype declaration in SVG files  [boolean] [default: true]
  --svg-namespace-ids            Whether to apply ID namespacing to the sprite  [boolean] [default: true]
  --svg-namespace-classnames     Whether to apply CSS class namespacing to the sprite  [boolean] [default: true]
  --svg-dimattrs                 Whether to add width and height attributes to the sprite  [boolean] [default: true]
  --svg-rootattrs                Custom root attributes for the outermost <svg> element (external JSON file)
  --svg-precision                Floating point precision for CSS positioning values  [default: -1]

  -c, --css                      Activates the «css» mode  [boolean] [default: false]
  --css-dest                     Mode specific output directory  [default: "css"]
  --cl, --css-layout             Sprite layout ("vertical"/"horizontal"/"diagonal"/"packed")  [default: "packed"]
  --css-common                   Common CSS rule selector for all shapes  [default: null]
  --css-mixin                    Preprocessor mixin name with properties for all shapes  [default: null]
  --css-prefix                   CSS selector prefix for all shapes (including placeholders)  [default: ".svg-%s"]
  --css-dimensions               CSS selector suffix for shape dimension rules ("" for inline)  [default: "-dims"]
  --cs, --css-sprite             Sprite path and filename (relative to --css-dest)  [default: "svg/sprite.css.svg"]
  --css-bust                     Enable cache busting  [boolean] [default: true]
  --ccss, --css-render-css       Whether to render a CSS stylesheet  [boolean] [default: false]
  --css-render-css-template      CSS stylesheet Mustache template (relative to svg-sprite basedir)  [default: "tmpl/css/sprite.css"]
  --css-render-css-dest          CSS stylesheet destination (relative to the --css-dest)  [default: "sprite.css"]
  --cscss, --css-render-scss     Whether to render a Sass stylesheet (SCSS)  [boolean] [default: false]
  --css-render-scss-template     Sass stylesheet Mustache template (relative to svg-sprite basedir)  [default: "tmpl/css/sprite.scss"]
  --css-render-scss-dest         Sass stylesheet destination (relative to the --css-dest)  [default: "sprite.scss"]
  --cless, --css-render-less     Whether to render a LESS stylesheet  [boolean] [default: false]
  --css-render-less-template     LESS stylesheet Mustache template (relative to svg-sprite basedir)  [default: "tmpl/css/sprite.less"]
  --css-render-less-dest         LESS stylesheet destination (relative to the --css-dest)  [default: "sprite.less"]
  --cstyl, --css-render-styl     Whether to render a Stylus stylesheet  [boolean] [default: false]
  --css-render-styl-template     Stylus stylesheet Mustache template (relative to svg-sprite basedir)  [default: "tmpl/css/sprite.styl"]
  --css-render-styl-dest         styl stylesheet destination (relative to the --css-dest)  [default: "sprite.styl"]
  --css-render-*                 Custom output renderings
  --css-render-*-template        Custom output Mustache template (relative to svg-sprite basedir)
  --css-render-*-dest            Custom output destination (relative to the --css-dest)
  --cx, --css-example            Whether to render an example HTML document  [boolean] [default: false]
  --css-example-template         HTML document Mustache template (relative to svg-sprite basedir)  [default: "tmpl/css/sprite.html"]
  --css-example-dest             HTML document destination (relative to the --css-dest)  [default: "sprite.css.html"]

  -v, --view                     Activates the «view» mode  [boolean] [default: false]
  --view-dest                    Mode specific output directory  [default: "view"]
  --vl, --view-layout            Sprite layout ("vertical"/"horizontal"/"diagonal"/"packed")  [default: "packed"]
  --view-common                  Common CSS rule selector for all shapes  [default: null]
  --view-mixin                   Preprocessor mixin name with properties for all shapes  [default: null]
  --view-prefix                  CSS selector prefix for all shapes (including placeholders)  [default: ".svg-%s"]
  --view-dimensions              CSS selector suffix for shape dimension rules ("" for inline)  [default: "-dims"]
  --vs, --view-sprite            Sprite path and filename (relative to --view-dest)  [default: "svg/sprite.css.svg"]
  --view-bust                    Enable cache busting  [boolean] [default: true]
  --vcss, --view-render-css      Whether to render a CSS stylesheet  [boolean] [default: false]
  --view-render-css-template     CSS stylesheet Mustache template (relative to svg-sprite basedir)  [default: "tmpl/css/sprite.css"]
  --view-render-css-dest         CSS stylesheet destination (relative to the --view-dest)  [default: "sprite.css"]
  --vscss, --view-render-scss    Whether to render a Sass stylesheet (SCSS)  [boolean] [default: false]
  --view-render-scss-template    Sass stylesheet Mustache template (relative to svg-sprite basedir)  [default: "tmpl/css/sprite.scss"]
  --view-render-scss-dest        Sass stylesheet destination (relative to the --view-dest)  [default: "sprite.scss"]
  --vless, --view-render-less    Whether to render a LESS stylesheet  [boolean] [default: false]
  --view-render-less-template    LESS stylesheet Mustache template (relative to svg-sprite basedir)  [default: "tmpl/css/sprite.less"]
  --view-render-less-dest        LESS stylesheet destination (relative to the --view-dest)  [default: "sprite.less"]
  --vstyl, --view-render-styl    Whether to render a Stylus stylesheet  [boolean] [default: false]
  --view-render-styl-template    Stylus stylesheet Mustache template (relative to svg-sprite basedir)  [default: "tmpl/css/sprite.styl"]
  --view-render-styl-dest        styl stylesheet destination (relative to the --view-dest)  [default: "sprite.styl"]
  --view-render-*                Custom output renderings
  --view-render-*-template       Custom output Mustache template (relative to svg-sprite basedir)
  --view-render-*-dest           Custom output destination (relative to the --view-dest)
  --vx, --view-example           Whether to render an example HTML document  [boolean] [default: false]
  --view-example-template        HTML document Mustache template (relative to svg-sprite basedir)  [default: "tmpl/view/sprite.html"]
  --view-example-dest            HTML document destination (relative to the --view-dest)  [default: "sprite.view.html"]

  -d, --defs                     Activates the «defs» mode  [boolean] [default: false]
  --defs-dest                    Mode specific output directory  [default: "defs"]
  --defs-prefix                  CSS selector prefix for all shapes (including placeholders)  [default: ".svg-%s"]
  --defs-dimensions              CSS selector suffix for shape dimension rules ("" for inline)  [default: "-dims"]
  --ds, --defs-sprite            Sprite path and filename (relative to --defs-dest)  [default: "svg/sprite.css.svg"]
  --defs-bust                    Enable cache busting  [boolean] [default: false]
  --dcss, --defs-render-css      Whether to render a CSS stylesheet  [boolean] [default: false]
  --defs-render-css-template     CSS stylesheet Mustache template (relative to svg-sprite basedir)  [default: "tmpl/css/sprite.css"]
  --defs-render-css-dest         CSS stylesheet destination (relative to the --defs-dest)  [default: "sprite.css"]
  --dscss, --defs-render-scss    Whether to render a Sass stylesheet (SCSS)  [boolean] [default: false]
  --defs-render-scss-template    Sass stylesheet Mustache template (relative to svg-sprite basedir)  [default: "tmpl/css/sprite.scss"]
  --defs-render-scss-dest        Sass stylesheet destination (relative to the --defs-dest)  [default: "sprite.scss"]
  --dless, --defs-render-less    Whether to render a LESS stylesheet  [boolean] [default: false]
  --defs-render-less-template    LESS stylesheet Mustache template (relative to svg-sprite basedir)  [default: "tmpl/css/sprite.less"]
  --defs-render-less-dest        LESS stylesheet destination (relative to the --defs-dest)  [default: "sprite.less"]
  --dstyl, --defs-render-styl    Whether to render a Stylus stylesheet  [boolean] [default: false]
  --defs-render-styl-template    Stylus stylesheet Mustache template (relative to svg-sprite basedir)  [default: "tmpl/css/sprite.styl"]
  --defs-render-styl-dest        styl stylesheet destination (relative to the --defs-dest)  [default: "sprite.styl"]
  --defs-render-*                Custom output renderings
  --defs-render-*-template       Custom output Mustache template (relative to svg-sprite basedir)
  --defs-render-*-dest           Custom output destination (relative to the --defs-dest)
  --di, --defs-inline            Create sprite variant suitable for inline embedding  [boolean] [default: false]
  --dx, --defs-example           Whether to render an example HTML document  [boolean] [default: false]
  --defs-example-template        HTML document Mustache template (relative to svg-sprite basedir)  [default: "tmpl/defs/sprite.html"]
  --defs-example-dest            HTML document destination (relative to the --defs-dest)  [default: "sprite.defs.html"]

  -s, --symbol                   Activates the «symbol» mode  [boolean] [default: false]
  --symbol-dest                  Mode specific output directory  [default: "symbol"]
  --symbol-prefix                CSS selector prefix for all shapes (including placeholders)  [default: ".svg-%s"]
  --symbol-dimensions            CSS selector suffix for shape dimension rules ("" for inline)  [default: "-dims"]
  --ss, --symbol-sprite          Sprite path and filename (relative to --css-dest)  [default: "svg/sprite.css.svg"]
  --symbol-bust                  Enable cache busting  [boolean] [default: false]
  --scss, --symbol-render-css    Whether to render a CSS stylesheet  [boolean] [default: false]
  --symbol-render-css-template   CSS stylesheet Mustache template (relative to svg-sprite basedir)  [default: "tmpl/css/sprite.css"]
  --symbol-render-css-dest       CSS stylesheet destination (relative to the --symbol-dest)  [default: "sprite.css"]
  --sscss, --symbol-render-scss  Whether to render a Sass stylesheet (SCSS)  [boolean] [default: false]
  --symbol-render-scss-template  Sass stylesheet Mustache template (relative to svg-sprite basedir)  [default: "tmpl/css/sprite.scss"]
  --symbol-render-scss-dest      Sass stylesheet destination (relative to the --symbol-dest)  [default: "sprite.scss"]
  --sless, --symbol-render-less  Whether to render a LESS stylesheet  [boolean] [default: false]
  --symbol-render-less-template  LESS stylesheet Mustache template (relative to svg-sprite basedir)  [default: "tmpl/css/sprite.less"]
  --symbol-render-less-dest      LESS stylesheet destination (relative to the --symbol-dest)  [default: "sprite.less"]
  --sstyl, --symbol-render-styl  Whether to render a Stylus stylesheet  [boolean] [default: false]
  --symbol-render-styl-template  Stylus stylesheet Mustache template (relative to svg-sprite basedir)  [default: "tmpl/css/sprite.styl"]
  --symbol-render-styl-dest      styl stylesheet destination (relative to the --symbol-dest)  [default: "sprite.styl"]
  --symbol-render-*              Custom output renderings
  --symbol-render-*-template     Custom output Mustache template (relative to svg-sprite basedir)
  --symbol-render-*-dest         Custom output destination (relative to the --symbol-dest)
  --si, --symbol-inline          Create sprite variant suitable for inline embedding  [boolean] [default: false]
  --sx, --symbol-example         Whether to render an example HTML document  [boolean] [default: false]
  --symbol-example-template      HTML document Mustache template (relative to svg-sprite basedir)  [default: "tmpl/symbol/sprite.html"]
  --symbol-example-dest          HTML document destination (relative to the --css-dest)  [default: "sprite.symbol.html"]

  -S, --stack                    Activates the «stack» mode  [boolean] [default: false]
  --stack-dest                   Mode specific output directory  [default: "stack"]
  --stack-prefix                 CSS selector prefix for all shapes (including placeholders)  [default: ".svg-%s"]
  --stack-dimensions             CSS selector suffix for shape dimension rules ("" for inline)  [default: "-dims"]
  --Ss, --stack-sprite           Sprite path and filename (relative to --css-dest)  [default: "svg/sprite.css.svg"]
  --stack-bust                   Enable cache busting  [boolean] [default: false]
  --Scss, --stack-render-css     Whether to render a CSS stylesheet  [boolean] [default: false]
  --stack-render-css-template    CSS stylesheet Mustache template (relative to svg-sprite basedir)  [default: "tmpl/css/sprite.css"]
  --stack-render-css-dest        CSS stylesheet destination (relative to the --stack-dest)  [default: "sprite.css"]
  --Sscss, --stack-render-scss   Whether to render a Sass stylesheet (SCSS)  [boolean] [default: false]
  --stack-render-scss-template   Sass stylesheet Mustache template (relative to svg-sprite basedir)  [default: "tmpl/css/sprite.scss"]
  --stack-render-scss-dest       Sass stylesheet destination (relative to the --stack-dest)  [default: "sprite.scss"]
  --Sless, --stack-render-less   Whether to render a LESS stylesheet  [boolean] [default: false]
  --stack-render-less-template   LESS stylesheet Mustache template (relative to svg-sprite basedir)  [default: "tmpl/css/sprite.less"]
  --stack-render-less-dest       LESS stylesheet destination (relative to the --stack-dest)  [default: "sprite.less"]
  --Sstyl, --stack-render-styl   Whether to render a Stylus stylesheet  [boolean] [default: false]
  --stack-render-styl-template   Stylus stylesheet Mustache template (relative to svg-sprite basedir)  [default: "tmpl/css/sprite.styl"]
  --stack-render-styl-dest       styl stylesheet destination (relative to the --stack-dest)  [default: "sprite.styl"]
  --stack-render-*               Custom output renderings
  --stack-render-*-template      Custom output Mustache template (relative to svg-sprite basedir)
  --stack-render-*-dest          Custom output destination (relative to the --stack-dest)
  --Sx, --stack-example          Whether to render an example HTML document  [boolean] [default: false]
  --stack-example-template       HTML document Mustache template (relative to svg-sprite basedir)  [default: "tmpl/stack/sprite.html"]
  --stack-example-dest           HTML document destination (relative to the --css-dest)  [default: "sprite.stack.html"]

  --variables                    Path to external JSON file with Mustache variable definitions

Examples

Both the following commands are doing the same (with the second one using the shorter argument syntax): They use the SVG files found in the directory "assets", create a CSS sprite of them and write them to the subdirectory "out" along with accompanying CSS stylesheets.

svg-sprite --css --css-render-css --css-example --dest=out assets/*.svg
# or
svg-sprite -cD out --ccss --cx assets/*.svg

The next one renders a Sass stylesheet (instead of plain CSS) and adds a 10px padding around all shapes in the sprite:

svg-sprite -cD out --cscss -p 10 assets/*.svg

Using config file (config.json in project base path) instead of command-line options. A config file can be generated with the online configurator.

svg-sprite --config config.json assets/*.svg

Advanced globbing

Some shells don't support the double-star character ** for matching files in an arbitrary directory depth, so you should wrap your glob expression in single quotes when using it in your pattern. This will prevent your shell from trying to resolve it and rather delegate globbing to Node instead (which does support the ** character).

svg-sprite --config config.json 'assets/**/*.svg'

The CLI typically uses only the basename of files for constructing the shape IDs in your sprite. That is, if an SVG source file is found at the path assets/path/to/source.svg, the shape inside the sprite will have the ID source. If you want to set a "base directory" from where ID traversal should start, simply add a symbolic link to that very same directory ("./") in your pattern:

svg-sprite --config config.json 'assets/./**/*.svg'

The spriter will then use path/to/source for ID creation, resulting in the shape ID path--to--source (assuming you don't override the default shape ID generator function). Please be aware that the described feature won't work if the matched SVG files are symbolic links themselves.

Inlined shape dimensions

To get the shape dimensions inlined into the main shape CSS rules, you need to pass an empty dimension selector suffix. There are two ways of doing so:

svg-sprite -cD out --css-dimensions "" --ccss assets/*.svg
# or
svg-sprite -cD out --css-dimensions= --ccss assets/*.svg