postcss-svg

PostCSS SVG

PostCSS SVG lets you inline SVGs in CSS.

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

/* after postcss-svg ↓ */

.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 build tool:

npm install postcss-svg --save-dev

Node

Use PostCSS SVG to process your CSS:

require('postcss-svg').process(YOUR_CSS);

PostCSS

Add PostCSS to your build tool:

npm install postcss --save-dev

Use PostCSS SVG as a plugin:

postcss([
  require('postcss-svg')()
]).process(YOUR_CSS);

Gulp

Add Gulp PostCSS to your build tool:

npm install gulp-postcss --save-dev

Use PostCSS SVG in your Gulpfile:

var postcss = require('gulp-postcss');

gulp.task('css', function () {
  return gulp.src('./src/*.css').pipe(
    postcss([
      require('postcss-svg')()
    ])
  ).pipe(
    gulp.dest('.')
  );
});

Grunt

Add Grunt PostCSS to your build tool:

npm install grunt-postcss --save-dev

Use PostCSS SVG in your Gruntfile:

grunt.loadNpmTasks('grunt-postcss');

grunt.initConfig({
  postcss: {
    options: {
      use: [
        require('postcss-svg')()
      ]
    },
    dist: {
      src: '*.css'
    }
  }
});

Advanced Usage

Additional directories can be specified for locating SVGs.

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

UTF-8 encoding can be swapped for base64 encoding.

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

svgo compression can be easily enabled and configured.

require('postcss-svg')({
  svgo: { plugins: [{ cleanupAttrs: true }] } /* Whether and how to use svgo compression. Default is false. */
})

Changelog

2.3.0 (November 2, 2017)

• Update SVGO to 1.x
• Improve SVG file resolution
• Improve SVG file caching