| 1 |
# svg-url-loader |
| 2 |
[![NPM version][npm-version-image]][npm-url] [![NPM downloads][npm-downloads-image]][npm-url] [![Dependencies][deps-image]][deps-url] [![Dev. Dependencies][dev-deps-image]][dev-deps-url] [![MIT License][license-image]][license-url] [![Build Status][travis-image]][travis-url] |
| 3 |
|
| 4 |
A webpack loader which loads SVG file as utf-8 encoded DataUrl string. |
| 5 |
|
| 6 |
Existing [`url-loader`](https://github.com/webpack-contrib/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](http://www.ietf.org/rfc/rfc1738.txt) and replace `"` with `'` as described [in this article](http://codepen.io/Tigt/post/optimizing-svgs-in-data-uris). |
| 7 |
|
| 8 |
There are some benefits for choosing utf-8 encoding over base64. |
| 9 |
1. Resulting string is shorter (can be ~2 times shorter for 2K-sized icons); |
| 10 |
2. Resulting string will be compressed better when using gzip compression; |
| 11 |
3. Browser parses utf-8 encoded string faster than its base64 equivalent. |
| 12 |
|
| 13 |
## Supported parameters |
| 14 |
|
| 15 |
Parameters can be passed both in a url or from webpack config file. See [Loaders](https://webpack.js.org/concepts/loaders/) section in webpack documentation for more details. |
| 16 |
|
| 17 |
The loader supports the following parameters: |
| 18 |
|
| 19 |
### `limit` |
| 20 |
|
| 21 |
If given will tell the loader not to encode the source file if its content is greater than this limit. |
| 22 |
Defaults to no limit. |
| 23 |
If the file is greater than the limit the [`file-loader`](https://github.com/webpack-contrib/file-loader) is used and all query parameters are passed to it. |
| 24 |
|
| 25 |
``` javascript |
| 26 |
require('svg-url-loader?limit=1024!./file.svg'); |
| 27 |
// => DataUrl if "file.png" is smaller that 1kb |
| 28 |
|
| 29 |
require('svg-url-loader?prefix=img/!./file.svg'); |
| 30 |
// => Parameters for the file-loader are valid too |
| 31 |
// They are passed to the file-loader if used. |
| 32 |
``` |
| 33 |
|
| 34 |
### `stripdeclarations` |
| 35 |
|
| 36 |
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. |
| 37 |
Internet Explorer (tested in Edge 14) cannot handle XML declarations in CSS data URLs (`content: url("data:image/svg...")`). |
| 38 |
|
| 39 |
``` javascript |
| 40 |
require('svg-url-loader?stripdeclarations!./file.svg'); |
| 41 |
``` |
| 42 |
|
| 43 |
### `iesafe` |
| 44 |
|
| 45 |
This option falls back to the file-loader if the file contains a style-element and the encoded size is above 4kB no matter the `limit` specified. |
| 46 |
|
| 47 |
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. |
| 48 |
|
| 49 |
``` javascript |
| 50 |
require('svg-url-loader?iesafe!./file.svg'); |
| 51 |
``` |
| 52 |
|
| 53 |
### `encoding` |
| 54 |
|
| 55 |
This option controls which encoding to use when constructing a data-URI for an SVG. When set to a non-"none" value, quotes are never applied to the outputted data-URI. |
| 56 |
|
| 57 |
Possible values are "base64" and "none". Defaults to "none". |
| 58 |
|
| 59 |
``` javascript |
| 60 |
require('svg-url-loader?encoding=base64!./file.svg'); |
| 61 |
``` |
| 62 |
|
| 63 |
## Usage |
| 64 |
|
| 65 |
[Documentation: Loaders](https://webpack.js.org/concepts/loaders/) |
| 66 |
|
| 67 |
### In JS: |
| 68 |
``` javascript |
| 69 |
require('svg-url-loader!./file.svg'); |
| 70 |
// => DataUrl for file.svg |
| 71 |
``` |
| 72 |
|
| 73 |
### In CSS (with webpack.config.js below): |
| 74 |
``` css |
| 75 |
.icon { |
| 76 |
background: url('../images/file.svg'); |
| 77 |
} |
| 78 |
``` |
| 79 |
``` javascript |
| 80 |
module.exports = { |
| 81 |
//... |
| 82 |
module: { |
| 83 |
rules: [ |
| 84 |
{ |
| 85 |
test: /\.svg/, |
| 86 |
use: { |
| 87 |
loader: 'svg-url-loader', |
| 88 |
options: {} |
| 89 |
} |
| 90 |
} |
| 91 |
] |
| 92 |
}, |
| 93 |
//... |
| 94 |
}; |
| 95 |
``` |
| 96 |
|
| 97 |
## License |
| 98 |
|
| 99 |
MIT (http://www.opensource.org/licenses/mit-license.php) |
| 100 |
|
| 101 |
[deps-image]: https://img.shields.io/david/bhovhannes/svg-url-loader.svg |
| 102 |
[deps-url]: https://david-dm.org/bhovhannes/svg-url-loader |
| 103 |
|
| 104 |
[dev-deps-image]: https://img.shields.io/david/dev/bhovhannes/svg-url-loader.svg |
| 105 |
[dev-deps-url]: https://david-dm.org/bhovhannes/svg-url-loader#info=devDependencies |
| 106 |
|
| 107 |
[license-image]: http://img.shields.io/badge/license-MIT-blue.svg?style=flat |
| 108 |
[license-url]: LICENSE |
| 109 |
|
| 110 |
[npm-url]: https://www.npmjs.org/package/svg-url-loader |
| 111 |
[npm-version-image]: https://img.shields.io/npm/v/svg-url-loader.svg?style=flat |
| 112 |
[npm-downloads-image]: https://img.shields.io/npm/dm/svg-url-loader.svg?style=flat |
| 113 |
|
| 114 |
[travis-url]: https://travis-ci.com/bhovhannes/svg-url-loader |
| 115 |
[travis-image]: https://img.shields.io/travis/bhovhannes/svg-url-loader.svg?style=flat |