A rehype plugin that inlines and optimizes SVG images
- Replaces SVG
<img>tags with inlined<svg>tags- Reduces extra HTTP requests to fetch tiny SVG files
- Gives you fine-grained control of images using CSS
- Optimizes SVGs using svgo
- Minimizes download size
- Removes extra metadata that is added by image editors
- Caches file reads
- Each
.svgfile is only read from disk once and optimized once - Improves processing speed when images occur multiple times on a page
- Improves processing speed when processing multiple HTML pages
- Each
This example uses to-vfile to read an HTML file and process it using unified, rehype-parse, and rehype-stringify.
index.html
<html>
<body>
<img src="img/icon.svg" alt="some icon">
</body>
</html>example.js
const unified = require("unified");
const parse = require("rehype-parse");
const inlineSVG = require("@jsdevtools/rehype-inline-svg");
const stringify = require("rehype-stringify");
const vfile = require("to-vfile");
async function example() {
// Create a Rehype processor with the Inline SVG plugin
const processor = unified()
.use(parse)
.use(inlineSVG)
.use(stringify);
// Read an HTML file that contains SVG images
let originalFile = await vfile.read("index.html");
// Process the file, inlining and optimizing SVG images
let modifiedFile = await processor.process(originalFile);
// The result is HTML with inlined <svg> elements
console.log(modifiedFile.contents);
// <html>
// <body>
// <svg alt="some icon" viewBox="0 0 48 48"><path d="M5 24c0...
// </body>
// </html>
}You can install Rehype Inline SVG via npm.
npm install @jsdevtools/rehype-inline-svgYou'll probably want to install unified, rehype-parse, rehype-stringify, and to-vfile as well.
npm install unified rehype-parse rehype-stringify to-vfileUsing the Inline SVG plugin requires an understanding of how to use Unified and Rehype. Here is an excelleng guide to learn the basics.
The Inline SVG plugin works just like any other Rehype plugin. Pass it to the .use() method, optionally with an options object.
const unified = require("unified");
const inlineSVG = require("@jsdevtools/rehype-inline-svg");
// Use the Inline SVG plugin with its default options
unified().use(inlineSVG);
// Use the Inline SVG plugin with custom options
unified().use(inlineSVG, {
maxImageSize: 5000, // Don't inline SVGs larger than 5 kb
maxTotalSize: 25000, // 25 kb limit for all occurrences of each SVG
optimize: false, // Don't optimize SVGs
});Rehype Inline SVG supports the following options:
| Option | Type | Default | Description |
|---|---|---|---|
maxImageSize |
number |
3000 |
The maximum image size (in bytes) to inline. Images that are larger than this (after optimization) will not be inlined. Defaults to ~3 kilobytes. |
maxOccurrences |
number |
Infinity |
The maximum number of times that the same image can appear on a page and still be inlined. Images that occur more than this number of times will not be inlined. |
maxTotalSize |
number |
10000 |
The maximum total size (in bytes) of all occurrences of a single image. If maxTotalSize is 10kb and a 2kb image occurs 5 times on a page, then all five occurrences will be inlined. But if the image accurs 6 or more times, then none of them will be inlined.Defaults to ~10 kilobytes. |
optimize |
boolean or object |
true |
SVG optimization options. If false, then SVGs will not be optimized. If true, then the default optimization options will be used. |
Contributions, enhancements, and bug-fixes are welcome! Open an issue on GitHub and submit a pull request.
To build the project locally on your computer:
-
Clone this repo
git clone https://github.com/JS-DevTools/rehype-inline-svg.git -
Install dependencies
npm install -
Build the code
npm run build -
Run the tests
npm test
Rehype Inline SVG is 100% free and open-source, under the MIT license. Use it however you want.
This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.
Thanks to these awesome companies for their support of Open Source developers ❤
