svg-sprite-loader

What is svg-sprite-loader?

svg-sprite-loader is a Webpack loader that optimizes SVG files by creating SVG sprites. This allows for efficient use of SVGs in web applications by reducing the number of HTTP requests and improving performance.

What are svg-sprite-loader's main functionalities?

Basic Usage

This configuration sets up svg-sprite-loader to process SVG files and generate symbols with IDs based on the file name.

module.exports = {
  module: {
    rules: [
      {
        test: /\.svg$/,
        loader: 'svg-sprite-loader',
        options: {
          symbolId: 'icon-[name]'
        }
      }
    ]
  }
};

Custom Sprite Filename

This configuration extracts the SVGs into a single sprite file named 'custom-sprite.svg'.

module.exports = {
  module: {
    rules: [
      {
        test: /\.svg$/,
        loader: 'svg-sprite-loader',
        options: {
          extract: true,
          spriteFilename: 'custom-sprite.svg'
        }
      }
    ]
  }
};

Using with SVGO

This configuration uses svg-sprite-loader in combination with svgo-loader to optimize SVG files before creating the sprite.

module.exports = {
  module: {
    rules: [
      {
        test: /\.svg$/,
        use: [
          'svg-sprite-loader',
          {
            loader: 'svgo-loader',
            options: {
              plugins: [
                { removeTitle: true },
                { convertColors: { shorthex: false } },
                { convertPathData: false }
              ]
            }
          }
        ]
      }
    ]
  }
};

Other packages similar to svg-sprite-loader

svg-sprite

svg-sprite is a standalone tool for creating SVG sprites. It offers a wide range of configuration options and can be used outside of Webpack. Compared to svg-sprite-loader, it is more flexible but requires additional setup to integrate with build systems.

svgstore

svgstore is a Node.js library for creating SVG sprites. It is simpler and more lightweight compared to svg-sprite-loader, but it does not integrate directly with Webpack, requiring additional steps to use in a Webpack-based project.

gulp-svg-sprite

gulp-svg-sprite is a Gulp plugin for creating SVG sprites. It is similar in functionality to svg-sprite-loader but is designed to work within a Gulp build process rather than Webpack.

README

SVG Sprite Webpack Loader

It's like style-loader, but for SVGs. Features:

• Create a single SVG sprite from a set of images
• Raster image support (PNG, JPG and GIF)
• Custom sprite implementations

How it works

When you require an image, SVG sprite webpack loader will transform it into an SVG symbol and add it to the array using a special sprite class. When the browser event DOMContentLoaded fires, an image sprite will then be rendered and injected as the first child of document.body.

By default, require statements like require('svg-sprite!./image.svg') will return a symbol ID, so you can reference it later with SVG's <use> tag:

<svg>
  <use xlink:href="#id" />
</svg>

Raster images will be inlined (using base64) and wrapped with an <image> tag. Files like [e-mail] will be transformed with proper scale.

Custom sprite implementation

If you need custom behavior, use the spriteModule config option to specify the path of your sprite implementation module.

You can extend a default lib/web/sprite.js, or create your own. In the latter case you only need to implement the add method that accepts the symbol data as a string.

Installation

npm install svg-sprite-loader --save-dev

Example config

module.exports = {
  module: {
    loaders: [{
      test: /\.svg$/,
      loader: 'svg-sprite?' + JSON.stringify({
        name: '[name]_[hash]',
        prefixize: true,
        spriteModule: 'utils/my-custom-sprite'
      })
    }]
  }
};

or, using regular expressions to capture the SVG's filename:

module.exports = {
  module: {
    loaders: [{
      test: /\.svg$/,
      loader: 'svg-sprite?' + JSON.stringify({
        name: 'icon-[1]',
        prefixize: true,
        regExp: './my-folder/(.*)\\.svg'
      })
    }]
  }
};
// path-to-project/my-folder/name.svg > #icon-name

Configuration

• name configures a custom symbol ID name. Default is [name]. The following name patterns are supported:
  • [ext] - the extension of the image
  • [name] - the basename of the image
  • [path] - the path of the image
  • [hash] - the hash or the image content
  • [pathhash] - the hash or the image path
• angularBaseWorkaround adds a workaround for Angular.js 1.x issues with combining <base> and the history API (which is typical for Angular.js). Default is false.
• prefixize isolates an image content by prefixing its id, xlink:href and url(#id) elements. Default is true.
• spriteModule defines custom sprite implementation module path
• esModule configures whether to transpile the module to an ES-compatible format. When this option is set to true, the loader will produce module.exports.__esModule = true; module.exports['default'] = svg. Default is false. (This is useful for transpilers other than Babel.)

Using the loader with a <base> tag

SVG Sprite Loader works well with the <base> tag in normal cases, however, in situations where the <base> tag is used with the browser's history API to simulate location changing, this will often break SVG xlink:href inclusion.

There are a few ways to get around this:

• If you use Angular.js 1.x, simply enable the angularBaseWorkaround config option described above
• If you use Angular 2.x or newer, you can remove the <base> tag and provide the router with an appropriate APP_BASE_HREF value
• If you're using another framework, you have to:
  • resolve the full image URL using window.location (so its usage may look like <use xlink:href="https://yoursite.com/your/full/path#id">),
  • trigger the spriteLoaderLocationUpdated event when a new location has been loaded. The angularBaseWorkaround option is one example of this implementation.

Examples

Single image:

var id = require('svg-sprite!./image.svg');
// => 'image'

Set of images:

var files = require.context('svg-sprite!images/logos', false, /(twitter|facebook|youtube)\.svg$/);
files.keys().forEach(files);

Custom sprite behavior:

// my-sprite.js
var Sprite = require('node_modules/svg-sprite-loader/lib/web/sprite');
module.exports = new Sprite();

// my-app.jsx
var sprite = require('my-sprite');

class MyApplication extends React.Component {
  componentWillMount() {
    sprite.elem = sprite.render(document.body);
  }

  componentWillUnmount() {
    sprite.elem.parentNode.removeChild(sprite.elem);
  }
}

Using with React:

// icon.jsx
var GLYPHS = {
  PONY: require('img/pony.svg'),
  UNICORN: require('img/unicorn.svg')
};

class Icon extends React.Component {
  render() {
    var glyph = this.props.glyph;
    return (
      <svg className="icon" dangerouslySetInnerHTML={{__html: '<use xlink:href="' + glyph + '"></use>'}}/>
    )
  }
}

module.exports = Icon;
module.exports.GLYPHS = GLYPHS;

// some-component.jsx
var Icon = require('components/icon');
<Icon glyph={Icon.GLYPHS.UNICORN}>

Using with React 0.14+:

// icon.jsx
export default function Icon({glyph, width = 16 , height = 16, className = 'icon'}){
  return (
    <svg className={className} width={width} height={height}>
      <use xlinkHref={glyph} />
    </svg>
  );
}

// some-component.jsx
import Icon from './icon';
import help from './images/icons/Help.svg';

<Icon glyph={help} />