Add a Plugin

eleventy-plugin-svg-sprite

A high performance Eleventy universal plugin that compiles a directory of SVG files into a single SVG Sprite and adds shortcodes to embed SVG Sprite and SVG content in Eleventy templates.

The SVG Sprite is compiled once in Eleventy's beforeBuild hook and is only recompiled when an SVG file is added/modified in the directory. No more slow rebuilding issues where SVG sprites are recompiled for every page! Uses svg-sprite under the hood.

Installation

Available on npm.

npm install eleventy-plugin-svg-sprite --save-dev
# OR
yarn add eleventy-plugin-svg-sprite --dev

Open up your Eleventy config file (probably .eleventy.js) and add the plugin:

const svgSprite = require("eleventy-plugin-svg-sprite");

module.exports = function (eleventyConfig) {
  eleventyConfig.addPlugin(svgSprite, {
    path: "./src/assets/svg", // relative path to SVG directory
    // (MUST be defined when initialising plugin)
  });
};

Config Options

Option Type Default Description
path String (required) undefined relative path to svg directory
spriteConfig Object (see options.js) Options you want to pass to svg-sprite
globalClasses String (empty string) global classes for embedded SVGs (will not be overridden by custom classes)
defaultClasses String (empty string) default classes for embedded SVGs (overridden by custom classes)
svgSpriteShortcode String svgsprite Customise shortcode used to embed SVG sprite (see Including the SVG Sprite)
svgShortcode String svg Customise shortcode used to embed SVG content (see Embedding SVG Content)

Usage

If you want to jump right into the code, you can refer to the demo folder.

Including the SVG Sprite

Assuming that the plugin's svgSpriteShortcode is svgsprite (default), use the following syntax to include the compiled SVG sprite:

<!-- Nunjucks/Liquid  -->
{% svgsprite %}

<!-- Handlebars  -->
{{{ svgsprite }}}

<!-- 11ty.js -->
${this.svgsprite()}

Which will render the following:

<div hidden>
  <svg
    xmlns="http://www.w3.org/2000/svg"
    xmlns:xlink="http://www.w3.org/1999/xlink"
  >
    ...(compiled svg sprite)...
  </svg>
</div>

Embedding SVG Content

Assuming that the plugin's svgShortcode is svg (default), use the following syntax to embed an SVG file at the defined path (eg. "./src/assets/svg/demo.svg" when path is "./src/assets/svg").

Note: make sure you have included the SVG Sprite.

<!-- Nunjucks/Liquid  -->
{% svg "demo" %}

<!-- Handlebars  -->
{{{ svg "demo" }}}

<!-- 11ty.js -->
${this.svg("demo")}

Which will render the following (assuming that globalClasses: "svgicon", defaultClasses: "default-class" when the plugin is initialised):

<svg class="svgicon default-class">
  ...(SVG content for demo.svg that references SVG Sprite above)...
</svg>

Adding custom classes to your SVG

Adding custom classes will override classes defined in defaultClasses, but classes defined in globalClasses will remain.

<!-- Nunjucks/Liquid  -->
{% svg "demo", "custom-class" %}

<!-- Handlebars  -->
{{{ svg "demo" "custom-class"}}}

<!-- 11ty.js  -->
`${this.svg("demo", "custom-class")}`

Which will render the following (assuming that globalClasses: "svgicon", defaultClasses: "default-class" when the plugin is initialised):

<svg class="svgicon custom-class">
  ...(SVG content for demo.svg that references SVG Sprite above)...
</svg>

Using your own shortcode to render SVGs

You can write your own SVG shortcode if you prefer. To make sure the SVG is referenced correctly, you can use the snippet below to start. #svg- is the prefix created by svg-sprite and name would be the filename of the SVG without the .svg extension.

eleventyConfig.addShortcode("icon", function (name) {
  return `<svg><use xlink:href="#svg-${name}"></use></svg>`;
});

Credits

Support this project

ko-fi