README

Inline SVG plugin for rehype

A rehype plugin that inlines and optimizes SVG images

Features

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 .svg file 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

Example

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>
}

Installation

You can install Rehype Inline SVG via npm.

npm install @jsdevtools/rehype-inline-svg

You'll probably want to install unified, rehype-parse, rehype-stringify, and to-vfile as well.

npm install unified rehype-parse rehype-stringify to-vfile

Usage

Using 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
});

Options

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.

Contributing

Contributions, enhancements, and bug-fixes are welcome! Open an issue on GitHub and submit a pull request.

Building

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

License

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.