svg-url-loader

What is svg-url-loader?

The svg-url-loader npm package is a webpack loader that inlines SVGs as URLs. This can be useful for embedding SVGs directly into your CSS or JavaScript files, reducing the number of HTTP requests and potentially improving load times.

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

Inlining SVGs as URLs

This feature allows you to inline SVGs as URLs in your JavaScript or CSS files. The code sample shows a basic webpack configuration that uses svg-url-loader to process SVG files.

module.exports = {
  module: {
    rules: [
      {
        test: /\.svg$/,
        use: 'svg-url-loader'
      }
    ]
  }
};

Customizing URL encoding

This feature allows you to customize the URL encoding of the inlined SVGs. The code sample shows how to configure svg-url-loader to use base64 encoding for the SVG URLs.

module.exports = {
  module: {
    rules: [
      {
        test: /\.svg$/,
        use: {
          loader: 'svg-url-loader',
          options: {
            encoding: 'base64'
          }
        }
      }
    ]
  }
};

Limiting file size

This feature allows you to limit the size of the SVG files that are inlined. Files larger than the specified limit will be handled by the default file loader. The code sample shows how to set a limit of 10KB for inlining SVGs.

module.exports = {
  module: {
    rules: [
      {
        test: /\.svg$/,
        use: {
          loader: 'svg-url-loader',
          options: {
            limit: 10000
          }
        }
      }
    ]
  }
};

Other packages similar to svg-url-loader

url-loader

The url-loader package is a webpack loader that can inline files as data URLs. It supports various file types, including images, fonts, and SVGs. Compared to svg-url-loader, url-loader is more versatile as it can handle multiple file types, but it may require additional configuration for SVG-specific optimizations.

file-loader

The file-loader package is another webpack loader that handles file imports. Unlike svg-url-loader, file-loader does not inline files as URLs but instead copies them to the output directory and returns the URL to the file. This can be useful for larger files or when you do not want to inline the content.

svg-inline-loader

The svg-inline-loader package is a webpack loader that inlines SVGs directly into the HTML or JavaScript as inline SVG elements. This is different from svg-url-loader, which inlines SVGs as URLs. svg-inline-loader can be useful when you need to manipulate the SVG elements directly in the DOM.

README

svg-url-loader

A webpack loader which loads SVG file as utf-8 encoded DataUrl string.

Existing url-loader always does Base64 encoding for data-uri. As SVG content is a human-readable xml string, using base64 encoding is not mandatory. Instead, one may only escape unsafe characters and replace " with ' as described in this article.

There are some benefits for choosing utf-8 encoding over base64.

1. Resulting string is shorter (can be ~2 times shorter for 2K-sized icons);
2. Resulting string will be compressed better when using gzip compression;
3. Browser parses utf-8 encoded string faster than its base64 equivalent.

Supported parameters

Parameters can be passed both in an url or from webpack config file. See Loaders section in webpack documentation for more details.

Passing parameters using resourceQuery is also supported:

.selector {
  background-image: url(../assets/foo.svg?encoding=base64);
}

The loader supports the following parameters:

limit

If given, loader will not encode the source file if its content is greater than this limit. Defaults to no limit. If the file is greater than the limit the file-loader is used, receiving all query parameters set for svg-url-loader.

require("svg-url-loader?limit=1024!./file.svg");
// => DataUrl if "file.png" is smaller that 1kb

require("svg-url-loader?prefix=img/!./file.svg");
// => Parameters for the file-loader are valid too
//    They are passed to the file-loader if used.

stripdeclarations

This option is true by default. It will be removed in the next major release.
See this issue for more context about this decision.

If given will tell the loader to strip out any XML declaration, e.g. <?xml version="1.0" encoding="UTF-8"?> at the beginning of imported SVGs. Internet Explorer (tested in Edge 14) cannot handle XML declarations in CSS data URLs (content: url("data:image/svg...")).

require("svg-url-loader?stripdeclarations!./file.svg");

iesafe

This option tells loader to fall back to the file-loader if the file contains a style-element and the encoded size is above 4kB no matter the limit specified.

This option was introduced because Internet Explorer (including IE11) stops parsing style-elements in SVG data-URIs longer than 4kB. This results in black fill-color for all styled shapes.

You can either specify iesafe option in the query:

// apply `iesafe` option only for 'foo.svg'
require("svg-url-loader?iesafe!./foo.svg");

Or, you can set this option globally in you webpack config:

module.exports = {
  //...
  module: {
    rules: [
      {
        test: /\.svg/,
        use: {
          loader: "svg-url-loader",
          options: {
            // make all svg images to work in IE
            iesafe: true,
          },
        },
      },
    ],
  },
  //...
};

encoding

This option controls which encoding to use when constructing a data-URI for an SVG. When set to a non-"none" value, loader does not apply quotes to the resulting data-URI.

Possible values are "base64" and "none". Defaults to "none".

Normally, setting encoding option to base64 should not be required, as using base64 encoding defeats the original purpose of this loader - embed svg with minimal size overhead. However, because of incompatibility with some tools, we support this mode, too.

You can either specify base64 option in the query:

// apply `base64` option only for 'foo.svg'
require("svg-url-loader?encoding=base64!./foo.svg");

Or, you can set this option globally in you webpack config:

module.exports = {
  //...
  module: {
    rules: [
      {
        test: /\.svg/,
        use: {
          loader: "svg-url-loader",
          options: {
            // make loader to behave like url-loader, for all svg files
            encoding: "base64",
          },
        },
      },
    ],
  },
  //...
};

Usage

Documentation: Loaders

In JS:

require("svg-url-loader!./file.svg");
// => DataUrl for file.svg

In CSS (with webpack.config.js below):

.icon {
  background: url("../images/file.svg");
}

module.exports = {
  //...
  module: {
    rules: [
      {
        test: /\.svg/,
        use: {
          loader: "svg-url-loader",
          options: {},
        },
      },
    ],
  },
  //...
};

Benefits of using data-uri

1. Browser won't make an extra http call to download the image
2. Some folks mentioned that even if image is in browser cache images with data url appear on screen faster.

License

MIT (http://www.opensource.org/licenses/mit-license.php)