{"id":15016577,"url":"https://github.com/patrickxchong/eleventy-plugin-svg-sprite","last_synced_at":"2025-08-12T22:40:27.129Z","repository":{"id":40568457,"uuid":"394317360","full_name":"patrickxchong/eleventy-plugin-svg-sprite","owner":"patrickxchong","description":"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.","archived":false,"fork":false,"pushed_at":"2025-06-17T04:26:26.000Z","size":289,"stargazers_count":41,"open_issues_count":4,"forks_count":6,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-09T05:27:32.765Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/patrickxchong.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-08-09T14:13:23.000Z","updated_at":"2025-06-17T04:26:30.000Z","dependencies_parsed_at":"2024-06-18T21:18:02.612Z","dependency_job_id":"9b0ed1dd-c785-4261-8c69-3ba2d135a720","html_url":"https://github.com/patrickxchong/eleventy-plugin-svg-sprite","commit_stats":{"total_commits":43,"total_committers":3,"mean_commits":"14.333333333333334","dds":"0.046511627906976716","last_synced_commit":"dd74681ebce72054fe43728287ad32c0e146d466"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/patrickxchong/eleventy-plugin-svg-sprite","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrickxchong%2Feleventy-plugin-svg-sprite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrickxchong%2Feleventy-plugin-svg-sprite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrickxchong%2Feleventy-plugin-svg-sprite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrickxchong%2Feleventy-plugin-svg-sprite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/patrickxchong","download_url":"https://codeload.github.com/patrickxchong/eleventy-plugin-svg-sprite/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrickxchong%2Feleventy-plugin-svg-sprite/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269699167,"owners_count":24461206,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-24T19:49:06.064Z","updated_at":"2025-08-12T22:40:27.029Z","avatar_url":"https://github.com/patrickxchong.png","language":"JavaScript","funding_links":["https://ko-fi.com/patrickxchong"],"categories":[],"sub_categories":[],"readme":"# eleventy-plugin-svg-sprite\n\nA high performance [Eleventy](https://github.com/11ty/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.\n\nThe SVG Sprite is compiled once in Eleventy's [beforeBuild](https://www.11ty.dev/docs/events/#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](https://github.com/svg-sprite/svg-sprite) under the hood.\n\n## Installation\n\nAvailable on [npm](https://www.npmjs.com/package/eleventy-plugin-svg-sprite).\n\n```bash\nnpm install eleventy-plugin-svg-sprite --save-dev\n# OR\nyarn add eleventy-plugin-svg-sprite --dev\n```\n\nOpen up your Eleventy config file (probably `.eleventy.js`) and add the plugin:\n\n```js\nconst svgSprite = require(\"eleventy-plugin-svg-sprite\");\n\nmodule.exports = function (eleventyConfig) {\n  eleventyConfig.addPlugin(svgSprite, {\n    path: \"./src/assets/svg\", // relative path to SVG directory\n    // (MUST be defined when initialising plugin)\n  });\n};\n```\n\nIf you would like to compile more than 1 svgsprite, pass an array of config objects with unique `svgSpriteShortcode` **(important)**:\n\n```js\nconst svgSprite = require(\"eleventy-plugin-svg-sprite\");\n\nmodule.exports = function (eleventyConfig) {\n  eleventyConfig.addPlugin(svgSprite, [\n    {\n      path: \"./src/assets/svg_1\", // relative path to SVG directory\n      svgSpriteShortcode: \"svgsprite1\",\n    },\n    {\n      path: \"./src/assets/svg_2\", // relative path to SVG directory\n      svgSpriteShortcode: \"svgsprite2\",\n    },\n  ]);\n};\n```\n\nRefer to [demo/array_config/.eleventy.js](./demo/array_config/.eleventy.js) for a sample.\n\n## Config Options\n\n| Option             | Type              | Default                              | Description                                                                                                                           |\n| ------------------ | ----------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |\n| path               | String (required) | undefined                            | relative path to svg directory                                                                                                        |\n| spriteConfig       | Object            | (see [options.js](./src/options.js)) | Options you want to pass to [svg-sprite](https://github.com/svg-sprite/svg-sprite)                                                    |\n| globalClasses      | String            | (empty string)                       | global classes for embedded SVGs (will not be overridden by [custom classes](#adding-custom-classes-to-your-svg))                     |\n| defaultClasses     | String            | (empty string)                       | default classes for embedded SVGs (overridden by [custom classes](#adding-custom-classes-to-your-svg))                                |\n| svgSpriteShortcode | String            | svgsprite                            | Customise shortcode used to embed SVG sprite (see [Including the SVG Sprite](#including-the-svg-sprite))                              |\n| svgShortcode       | String            | svg                                  | Customise shortcode used to embed SVG content (see [Embedding SVG Content](#embedding-svg-content))                                   |\n| outputFilepath     | String            | (empty string)                       | Filepath to write compiled spritesheet to (see [Exporting compiled spritesheet as a file](#exporting-compiled-spritesheet-as-a-file)). No file is created if `outputFilepath` is empty. |\n\n## Usage\n\nIf you want to jump right into the code, you can refer to the [demo](./demo) folder.\n\n### Including the SVG Sprite\n\nAssuming that the plugin's `svgSpriteShortcode` is `svgsprite` (default), use the following syntax to include the compiled SVG sprite:\n\n```html\n\u003c!-- Nunjucks/Liquid  --\u003e\n{% svgsprite %}\n\n\u003c!-- Handlebars  --\u003e\n{{{ svgsprite }}}\n\n\u003c!-- 11ty.js --\u003e\n${this.svgsprite()}\n```\n\nWhich will render the following:\n\n```html\n\u003cdiv hidden\u003e\n  \u003csvg\n    xmlns=\"http://www.w3.org/2000/svg\"\n    xmlns:xlink=\"http://www.w3.org/1999/xlink\"\n  \u003e\n    ...(compiled svg sprite)...\n  \u003c/svg\u003e\n\u003c/div\u003e\n```\n\n### Embedding SVG Content\n\nAssuming 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\"`).\n\nNote: make sure you have [included the SVG Sprite](#including-the-svg-sprite).\n\n```html\n\u003c!-- Nunjucks/Liquid  --\u003e\n{% svg \"demo\" %}\n\n\u003c!-- Handlebars  --\u003e\n{{{ svg \"demo\" }}}\n\n\u003c!-- 11ty.js --\u003e\n${this.svg(\"demo\")}\n```\n\nWhich will render the following (assuming that `globalClasses: \"svgicon\", defaultClasses: \"default-class\"` when the plugin is initialised):\n\n```html\n\u003csvg class=\"svgicon default-class\"\u003e\n  ...(SVG content for demo.svg that references SVG Sprite above)...\n\u003c/svg\u003e\n```\n\n### Adding custom classes to your SVG\n\nAdding custom classes will override classes defined in `defaultClasses`, but classes defined in `globalClasses` will remain.\n\n```html\n\u003c!-- Nunjucks/Liquid  --\u003e\n{% svg \"demo\", \"custom-class\" %}\n\n\u003c!-- Handlebars  --\u003e\n{{{ svg \"demo\" \"custom-class\"}}}\n\n\u003c!-- 11ty.js  --\u003e\n`${this.svg(\"demo\", \"custom-class\")}`\n```\n\nWhich will render the following (assuming that `globalClasses: \"svgicon\", defaultClasses: \"default-class\"` when the plugin is initialised):\n\n```html\n\u003csvg class=\"svgicon custom-class\"\u003e\n  ...(SVG content for demo.svg that references SVG Sprite above)...\n\u003c/svg\u003e\n```\n\n### SVG id naming convention\n\n```\n📂assets\n ┣ 📂svg\n   ┣ 📜 item.svg\n   ┣ 📂 sub_dir_1\n   ┃ ┗ 📜 item-1.svg\n   ┗ 📂 sub_dir_2\n     ┗ 📂 sub_sub_dir_2\n       ┗ 📜 example item 2.svg\n```\n\nFor a directory structure as above, the respective SVG ids generated are as follows:\n\n```js\nsvg \"item\" // no subdirectory prefix\nsvg \"sub_dir_1--item-1\" // one level subdirectory with '--' prefix\nsvg \"sub_dir_2--sub_sub_dir_2--example_item_2\" // two level subdirectory with '--' prefix, also convert spaces into '_'\n```\n\n### Using your own shortcode to render SVGs\n\nYou 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](#svg-id-naming-convention) for edge cases and other uses).\n\n```js\neleventyConfig.addShortcode(\"icon\", function (name) {\n  return `\u003csvg\u003e\u003cuse xlink:href=\"#svg-${name}\"\u003e\u003c/use\u003e\u003c/svg\u003e`;\n});\n```\n\n### Exporting compiled spritesheet as a file\n\nIf 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). \n\nAs an example, if `outputPath` is set to `\"./_site/sprites/icons.svg\"`, you can reference a file named `placeholder-feature.svg`with the following html snippet. (note the `svg-` prefix)\n```html\n\u003csvg\u003e\n  \u003cuse xlink:href=\"/sprites/icons.svg#svg-placeholder-feature\"\u003e\u003c/use\u003e\n\u003c/svg\u003e\n```\n\nRefer to [demo/file_output/.eleventy.js](./demo/array_config/.eleventy.js) for an example.\n\n## Credits\n\n- https://github.com/11ta/11ta-template for SVG compilation code and SVG shortcode\n- 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\n- [@daviddarnes](https://github.com/daviddarnes) for the suggestion of wrapping this code into a plugin\n\n## Support this project\n\n[![ko-fi](https://www.ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/patrickxchong)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatrickxchong%2Feleventy-plugin-svg-sprite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpatrickxchong%2Feleventy-plugin-svg-sprite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatrickxchong%2Feleventy-plugin-svg-sprite/lists"}