npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

eleventy-plugin-svg-sprite

v2.4.2

Published

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.

Downloads

2,403

Readme

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

If you would like to compile more than 1 svgsprite, pass an array of config objects with unique svgSpriteShortcode (important):

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

module.exports = function (eleventyConfig) {
  eleventyConfig.addPlugin(svgSprite, [
    {
      path: "./src/assets/svg_1", // relative path to SVG directory
      svgSpriteShortcode: "svgsprite1",
    },
    {
      path: "./src/assets/svg_2", // relative path to SVG directory
      svgSpriteShortcode: "svgsprite2",
    },
  ]);
};

Refer to demo/array_config/.eleventy.js for a sample.

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) | | outputFilepath | String | (empty string) | Filepath to write compiled spritesheet to (see Exporting compiled spritesheet as a file). No file is created if outputFilepath is empty. |

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>

SVG id naming convention

📂assets
 ┣ 📂svg
   ┣ 📜 item.svg
   ┣ 📂 sub_dir_1
   ┃ ┗ 📜 item-1.svg
   ┗ 📂 sub_dir_2
     ┗ 📂 sub_sub_dir_2
       ┗ 📜 example item 2.svg

For a directory structure as above, the respective SVG ids generated are as follows:

svg "item" // no subdirectory prefix
svg "sub_dir_1--item-1" // one level subdirectory with '--' prefix
svg "sub_dir_2--sub_sub_dir_2--example_item_2" // two level subdirectory with '--' prefix, also convert spaces into '_'

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 (also refer to SVG id naming convention for edge cases and other uses).

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

Exporting compiled spritesheet as a file

If you prefer to host the compiled spritesheet as a file/on a CDN instead of embedding the spritesheet in the template, you can specify outputFilepath in the config, which would write to the location of the path (be careful as it will overwrite any file that pre-exists at that path).

As an example, if outputPath is set to "./_site/sprites/icons.svg", you can reference a file named placeholder-feature.svgwith the following html snippet. (note the svg- prefix)

<svg>
  <use xlink:href="/sprites/icons.svg#svg-placeholder-feature"></use>
</svg>

Refer to demo/file_output/.eleventy.js for an example.

Credits

  • https://github.com/11ta/11ta-template for SVG compilation code and SVG shortcode
  • https://github.com/11ty/eleventy-plugin-syntaxhighlight, https://github.com/brob/eleventy-plugin-svg-contents and https://github.com/5t3ph/eleventy-plugin-template for Eleventy plugin structure
  • @daviddarnes for the suggestion of wrapping this code into a plugin

Support this project

ko-fi