{"id":18561179,"url":"https://github.com/apostrophecms/svg-sprite","last_synced_at":"2026-01-27T13:03:34.003Z","repository":{"id":45129926,"uuid":"437932181","full_name":"apostrophecms/svg-sprite","owner":"apostrophecms","description":null,"archived":false,"fork":false,"pushed_at":"2024-10-31T13:37:14.000Z","size":38,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-25T15:23:26.783Z","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/apostrophecms.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","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}},"created_at":"2021-12-13T15:48:57.000Z","updated_at":"2024-10-31T13:37:08.000Z","dependencies_parsed_at":"2024-03-28T15:46:52.761Z","dependency_job_id":"f096ce60-fe39-463b-9086-ac1490936104","html_url":"https://github.com/apostrophecms/svg-sprite","commit_stats":{"total_commits":37,"total_committers":7,"mean_commits":5.285714285714286,"dds":"0.45945945945945943","last_synced_commit":"e6d14d9313cf9bd8367acc2386deec3766d78da1"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/apostrophecms/svg-sprite","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apostrophecms%2Fsvg-sprite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apostrophecms%2Fsvg-sprite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apostrophecms%2Fsvg-sprite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apostrophecms%2Fsvg-sprite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apostrophecms","download_url":"https://codeload.github.com/apostrophecms/svg-sprite/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apostrophecms%2Fsvg-sprite/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28813229,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-27T12:25:15.069Z","status":"ssl_error","status_checked_at":"2026-01-27T12:25:05.297Z","response_time":168,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-11-06T22:06:04.156Z","updated_at":"2026-01-27T13:03:33.966Z","avatar_url":"https://github.com/apostrophecms.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/apostrophecms/apostrophe/main/logo.svg\" alt=\"ApostropheCMS logo\" width=\"80\" height=\"80\"\u003e\n\n  \u003ch1\u003eSVG Sprites for ApostropheCMS\u003c/h1\u003e\n  \u003cp\u003e\n    \u003ca aria-label=\"Apostrophe logo\" href=\"https://v3.docs.apostrophecms.org\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/MADE%20FOR%20ApostropheCMS-000000.svg?style=for-the-badge\u0026logo=Apostrophe\u0026labelColor=6516dd\"\u003e\n    \u003c/a\u003e\n    \u003ca aria-label=\"Test status\" href=\"https://github.com/apostrophecms/svg-sprite/actions\"\u003e\n      \u003cimg alt=\"GitHub Workflow Status (branch)\" src=\"https://img.shields.io/github/workflow/status/apostrophecms/svg-sprite/Tests/main?label=Tests\u0026labelColor=000000\u0026style=for-the-badge\"\u003e\n    \u003c/a\u003e\n    \u003ca aria-label=\"Join the community on Discord\" href=\"http://chat.apostrophecms.org\"\u003e\n      \u003cimg alt=\"\" src=\"https://img.shields.io/discord/517772094482677790?color=5865f2\u0026label=Join%20the%20Discord\u0026logo=discord\u0026logoColor=fff\u0026labelColor=000\u0026style=for-the-badge\u0026logoWidth=20\"\u003e\n    \u003c/a\u003e\n    \u003ca aria-label=\"License\" href=\"https://github.com/apostrophecms/svg-sprite/blob/main/LICENSE.md\"\u003e\n      \u003cimg alt=\"\" src=\"https://img.shields.io/static/v1?style=for-the-badge\u0026labelColor=000000\u0026label=License\u0026message=MIT\u0026color=3DA639\"\u003e\n    \u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\nThis module provides an Apostrophe piece type that manages and renders SVG sprites. Sprites can be imported from files in a website codebase or an external source via a URL.\n\nSVG sprites must be generated by a separate process. The module does not provide functionality to build the sprite files. [See below](#sprite-file-markup) for sprite markup requirements.\n\n## Installation\n\nTo install the module, use the command line to run this command in an Apostrophe project's root directory:\n\n```\nnpm install @apostrophecms/svg-sprite\n```\n\n## Usage\n\nConfigure the SVG Sprite module in the `app.js` file:\n\n```javascript\nrequire('apostrophe')({\n  shortName: 'my-project',\n  modules: {\n    '@apostrophecms/svg-sprite': {}\n  }\n});\n```\n\nThe SVG Sprites module should then be configured in its own `index.js` file with information about the sprite maps. Sprite files should be registered in the `maps` option, set to an array of configuration objects.\n\n```javascript\n// modules/@apostrophecms/svg-sprite/index.js\nmodule.exports = {\n  options: {\n    maps: [\n      {\n        label: 'Places Icons',\n        name: 'places',\n        file: 'svg/places.svg'\n      },\n      {\n        label: 'Service Icons',\n        name: 'services',\n        file: 'svg/services.svg'\n      }\n    ]\n  }\n}\n```\n\nThe configuration objects include:\n\n- `label`: A clear label for the group of sprites.\n- `name`: A string with no whitespace that is unique within the project.\n- `file`: The location of the file. This may be a local file or a URL, as discussed below.\n\nThe sprites can be imported into Apostrophe as pieces by running the module's `import` task. This task will look for each registered sprite file and generate pieces (Apostrophe content) for each SVG. On the command line this task could be started from the project root with the following command:\n\n```bash\nnode app @apostrophecms/svg-sprite:import\n```\n\n### Sprite file location options\n\nThere are three options for registering SVG file locations:\n\n1. Use a partial file path to a specific file, e.g., `'svg/places.svg'`.\n2. Use a partial file path with wild card symbols, e.g., `'svg/*-icons.svg'`. See the [Glob package documentation](https://www.npmjs.com/package/glob#glob-primer) for acceptable patterns.\n3. Use a URL for an externally hosted file, e.g., `'http://myfiles.net/svg/icons.svg'`.\n\nWhen using the partial file path options, the module will look for those files in its own `public` directory: `modules/@apostrophecms/svg-sprite/public/`. For example, `'svg/places.svg'` would reference a file at `modules/@apostrophecms/svg-sprite/public/svg/places.svg` in the code base.\n\n### Sprite file markup\n\nSprite files use the [SVG `symbol` element](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/symbol) to include multiple SVG images within a single `svg` tag. See the [CSS-Tricks](https://css-tricks.com/svg-symbol-good-choice-icons/) guide for more information about how to construct and use these sprite files.\n\n**Requirements for this module include:**\n- Sprite maps must be formatted so that all `\u003csymbol\u003e...\u003csymbol/\u003e` elements are on the same node level. This simply means that `symbol` tags should not be nested within other `symbol` tags.\n- `symbol` tags must have an `id` attribute, e.g., `\u003csymbol id=\"bicycle\"\u003e...\u003c/symbol\u003e`.\n- `symbol` tags can *optionally* have a `title` attribute that will be used as the imported piece's title field, e.g., `\u003csymbol title=\"Bicycle icon\"\u003e...\u003c/symbol\u003e`\n\nHere is an example of sprite file markup (with the `path` values abbeviated):\n\n```html\n\u003csvg xmlns=\"http://www.w3.org/2000/svg\"\u003e\n\t\u003csymbol width=\"24\" height=\"24\" viewBox=\"0 0 24 24\" id=\"coffee_cup\" \u003e\n\t\t\u003cpath d=\"...\" /\u003e\n\t\u003c/symbol\u003e\n\t\u003csymbol width=\"24\" height=\"24\" viewBox=\"0 0 24 24\" id=\"bicycle\" \u003e\n\t\t\u003cpath d=\"...\" /\u003e\n\t\u003c/symbol\u003e\n\u003c/svg\u003e\n```\n\n### Using SVG sprite pieces\n\nThe primary properties we use to reference individual SVG symbols are:\n- `file`: The file path or URL to the full sprite map. This file still includes all symbols that were part of that original map file.\n- `svgId`: The `id` property of the individual SVG symbol. We have to use this in combination with the file path to get a specific symbol.\n- `map`: The `map` name property can be used to quickly find one of the sprite maps that were configured in the module's `maps` array.\n\nHTML markup using an individual SVG symbol might look like the example below. The example uses `svgSprite` as a reference to the individual piece content. A project might reference sprite pieces using a relationship field, for example.\n\n```django\n\u003csvg\u003e\n  \u003cuse xlink:href=\"{{ svgSprite.file }}#{{ svgSprite.id }}\"\u003e\u003c/use\u003e\n\u003c/svg\u003e\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapostrophecms%2Fsvg-sprite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapostrophecms%2Fsvg-sprite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapostrophecms%2Fsvg-sprite/lists"}