svgo: A JavaScript repository from juliaabrams

SVGO

SVG Optimizer is a Node.js-based tool for optimizing SVG vector graphics files.

Why?

SVG files, especially those exported from various editors, usually contain a lot of redundant and useless information. This can include editor metadata, comments, hidden elements, default or non-optimal values and other stuff that can be safely removed or converted without affecting the SVG rendering result.

Installation

Via npm:

npm -g install svgo

Via yarn:

yarn global add svgo

CLI usage

Processing single files:

svgo one.svg two.svg -o one.min.svg two.min.svg

Processing directory of svg files, recursively using -f, --folder:

svgo -f ./path/to/folder/with/svg/files -o ./path/to/folder/with/svg/output

Help for advanced usage:

svgo --help

Configuration

SVGO has a plugin-based architecture, separate plugins allows various xml svg optimizations. See built-in plugins. SVGO automatically loads configuration from svgo.config.js or from --config ./path/myconfig.js. Some general options can be configured via CLI.

// svgo.config.js
module.exports = {
  multipass: true, // boolean. false by default
  datauri: 'enc', // 'base64' (default), 'enc' or 'unenc'.
  js2svg: {
    indent: 2, // string with spaces or number of spaces. 4 by default
    pretty: true, // boolean, false by default
  },
  plugins: [
    // set of built-in plugins enabled by default
    'preset-default',

    // enable built-in plugins by name
    'prefixIds',

    // or by expanded notation which allows to configure plugin
    {
      name: 'sortAttrs',
      params: {
        xmlnsOrder: 'alphabetical',
      },
    },
  ],
};

Default preset

When extending default configuration specify preset-default plugin to enable optimisations. Each plugin of default preset can be disabled or configured with "overrides" param.

module.exports = {
  plugins: [
    {
      name: 'preset-default',
      params: {
        overrides: {
          // customize default plugin options
          inlineStyles: {
            onlyMatchedOnce: false,
          },

          // or disable plugins
          removeDoctype: false,
        },
      },
    },
  ],
};

The default preset includes plugins marked with 'Yes' in the plugin list below.

Custom plugin

It's also possible to specify a custom plugin:

const anotherCustomPlugin = require('./another-custom-plugin.js');
module.exports = {
  plugins: [
    {
      name: 'customPluginName',
      params: {
        optionName: 'optionValue',
      },
      fn: (ast, params, info) => {},
    },
    anotherCustomPlugin,
  ],
};

API usage

SVGO provides a few low level utilities.

optimize

The core of SVGO is optimize function.

const { optimize } = require('svgo');
const result = optimize(svgString, {
  // optional but recommended field
  path: 'path-to.svg',
  // all config fields are also available here
  multipass: true,
});
const optimizedSvgString = result.data;

loadConfig

If you write a tool on top of SVGO you might need a way to load SVGO config.

const { loadConfig } = require('svgo');
const config = await loadConfig();

You can also specify a relative or absolute path and customize the current working directory.

const config = await loadConfig(configFile, cwd);

Troubleshooting

SVG won't scale when CSS is applied on it.

Observed Problem: I'm using my SVG files on a website. It looks like the rendered SVG doesn't scale when the dimensions are altered using CSS.

Possible Solution: Try disabling removeViewBox in the configuration. See issue #1128 for details and discussion.

Built-in plugins

Plugin	Description	Default
addAttributesToSVGElement	adds attributes to an outer `<svg>` element
addClassesToSVGElement	add classnames to an outer `<svg>` element
cleanupAttrs	cleanup attributes from newlines, trailing, and repeating spaces	Yes
cleanupEnableBackground	remove or cleanup `enable-background` attribute when possible	Yes
cleanupIds	remove unused and minify used IDs	Yes
cleanupListOfValues	round numeric values in attributes that take a list of numbers (like `viewBox` or `enable-background`)
cleanupNumericValues	round numeric values to the fixed precision, remove default `px` units	Yes
collapseGroups	collapse useless groups	Yes
convertColors	convert colors (from `rgb()` to `#rrggbb`, from `#rrggbb` to `#rgb`)	Yes
convertEllipseToCircle	convert non-eccentric `<ellipse>` to `<circle>`	Yes
convertPathData	convert Path data to relative or absolute (whichever is shorter), convert one segment to another, trim useless delimiters, smart rounding, and much more	Yes
convertShapeToPath	convert some basic shapes to `<path>`	Yes
convertStyleToAttrs	convert styles into attributes
convertTransform	collapse multiple transforms into one, convert matrices to the short aliases, and much more	Yes
inlineStyles	move and merge styles from `<style>` elements to element `style` attributes	Yes
mergePaths	merge multiple Paths into one	Yes
mergeStyles	merge multiple style elements into one	Yes
minifyStyles	minify `<style>` elements content with CSSO	Yes
moveElemsAttrsToGroup	move elements' attributes to their enclosing group	Yes
moveGroupAttrsToElems	move some group attributes to the contained elements	Yes
prefixIds	prefix IDs and classes with the SVG filename or an arbitrary string
removeAttributesBySelector	removes attributes of elements that match a CSS selector
removeAttrs	remove attributes by pattern
removeComments	remove comments	Yes
removeDesc	remove `<desc>`	Yes
removeDimensions	remove `width`/`height` and add `viewBox` if it's missing (opposite to removeViewBox, disable it first)
removeDoctype	remove `doctype` declaration	Yes
removeEditorsNSData	remove editors namespaces, elements, and attributes	Yes
removeElementsByAttr	remove arbitrary elements by `ID` or `className`
removeEmptyAttrs	remove empty attributes	Yes
removeEmptyContainers	remove empty Container elements	Yes
removeEmptyText	remove empty Text elements	Yes
removeHiddenElems	remove hidden elements	Yes
removeMetadata	remove `<metadata>`	Yes
removeNonInheritableGroupAttrs	remove non-inheritable group's "presentation" attributes	Yes
removeOffCanvasPaths	removes elements that are drawn outside of the viewbox
removeRasterImages	remove raster images
removeScriptElement	remove `<script>` elements
removeStyleElement	remove `<style>` elements
removeTitle	remove `<title>`	Yes
removeUnknownsAndDefaults	remove unknown elements content and attributes, remove attributes with default values	Yes
removeUnusedNS	remove unused namespaces declaration	Yes
removeUselessDefs	remove elements of `<defs>` without `id`	Yes
removeUselessStrokeAndFill	remove useless `stroke` and `fill` attributes	Yes
removeViewBox	remove `viewBox` attribute when possible	Yes
removeXMLNS	removes the `xmlns` attribute (for inline SVG)
removeXMLProcInst	remove XML processing instructions	Yes
reusePaths	Find duplicated elements and replace them with links
sortAttrs	sort element attributes for epic readability	Yes
sortDefsChildren	sort children of `<defs>` in order to improve compression	Yes

Other ways to use SVGO

Method	Reference
Web app	SVGOMG
GitHub Action	SVGO Action
Grunt task	grunt-svgmin
Gulp task	gulp-svgmin
Mimosa module	mimosa-minify-svg
OSX Folder Action	svgo-osx-folder-action
Webpack loader	image-webpack-loader
Telegram Bot	svgo_bot
PostCSS plugin	postcss-svgo
Inkscape plugin	inkscape-svgo
Sketch plugin	svgo-compressor
macOS app	Image Shrinker
Rollup plugin	rollup-plugin-svgo
VS Code plugin	vscode-svgo
Atom plugin	atom-svgo
Sublime plugin	Sublime-svgo
Figma plugin	Advanced SVG Export
Linux app	Oh My SVG
Browser extension	SVG Gobbler
API	Vector Express

Donors


SheetJS LLC	Fontello

License and Copyright

This software is released under the terms of the MIT license.

Logo by André Castillo.

juliaabrams/svgo