postcss-svg

PostCSS SVG

PostCSS SVG lets you inline SVGs in CSS.

.icon--square {
  content: url("shared-sprites#square" param(--color blue));
}

/* becomes */

.icon--square {
  content: url("data:image/svg+xml;charset=utf-8,%3Csvg xmlns='http://www.w3.org/2000/svg'%3E%3Crect style='fill:blue' width='100%25' height='100%25'/%3E%3C/svg%3E");
}

SVG Fragments let you reference elements within an SVG. SVG Parameters let you push compiled CSS variables into your SVGs.

<svg xmlns="http://www.w3.org/2000/svg">
  <symbol id="square">
    <rect style="fill:var(--color,black)" width="100%" height="100%"/>
  </symbol>
</svg>

Modules let you reference the media or main fields from a package.json:

{
  "name": "shared-sprites",
  "media": "sprites.svg"
}

The location of an SVG is intelligently resolved using the SVG Resolve Algorithm.

Usage

Add PostCSS SVG to your project:

npm install postcss-svg --save-dev

Use PostCSS SVG to process your CSS:

const postcssSVG = require('postcss-svg');

postcssSVG.process(YOUR_CSS /*, processOptions, pluginOptions */);

Or use it as a PostCSS plugin:

const postcss = require('postcss');
const postcssSVG = require('postcss-svg');

postcss([
  postcssSVG(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);

PostCSS SVG runs in all Node environments, with special instructions for:

Node	PostCSS CLI	Webpack	Create React App	Gulp	Grunt

Options

dirs

The dirs option specifies additional directories used to locate SVGs.

postcssSVG({
  dirs: ['some-folder', 'another-folder'] /* Just a string will work, too */
})

The utf8 option determines whether the SVG is UTF-8 encoded or base64 encoded.

postcssSVG({
  utf8: false /* Whether to use utf-8 or base64 encoding. Default is true. */
})

The svgo option determines whether and how svgo compression is used.

postcssSVG({
  svgo: { plugins: [{ cleanupAttrs: true }] } /* Whether and how to use svgo compression. Default is false. */
})