Inline SVG rehype plugin

A rehype plugin that inlines and optimizes SVG images

Inline SVG plugin for rehype

A rehype plugin that inlines and optimizes SVG images

Cross-Platform Compatibility Build Status

Coverage Status Dependencies

npm License

Features

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("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 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("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
  maxTotalFileSize: 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! File an issue on GitHub and submit a pull request.

Building

To build the project locally on your computer:

  1. Clone this repo
    git clone https://github.com/JS-DevTools/rehype-inline-svg.git

  2. Install dependencies
    npm install

  3. Build the code
    npm run build

  4. Run the tests
    npm test

License

rehype-inline-svg is 100% free and open-source, under the MIT license. Use it however you want.

Big Thanks To

Thanks to these awesome companies for their support of Open Source developers ❤

Travis CI SauceLabs Coveralls