{"id":21591986,"url":"https://github.com/thasmo/external-svg-polyfill","last_synced_at":"2025-04-10T22:53:16.509Z","repository":{"id":57165791,"uuid":"150168284","full_name":"thasmo/external-svg-polyfill","owner":"thasmo","description":"Small and basic polyfill to support referencing external SVG files.","archived":false,"fork":false,"pushed_at":"2021-02-04T10:25:03.000Z","size":108,"stargazers_count":6,"open_issues_count":2,"forks_count":2,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-04-10T22:53:10.243Z","etag":null,"topics":["browser","embed","external","fallback","inline","legacy","npm","polyfill","svg"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/thasmo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-09-24T21:03:57.000Z","updated_at":"2023-05-01T03:51:46.000Z","dependencies_parsed_at":"2022-08-30T15:10:28.281Z","dependency_job_id":null,"html_url":"https://github.com/thasmo/external-svg-polyfill","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thasmo%2Fexternal-svg-polyfill","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thasmo%2Fexternal-svg-polyfill/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thasmo%2Fexternal-svg-polyfill/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thasmo%2Fexternal-svg-polyfill/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thasmo","download_url":"https://codeload.github.com/thasmo/external-svg-polyfill/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248312172,"owners_count":21082638,"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","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":["browser","embed","external","fallback","inline","legacy","npm","polyfill","svg"],"created_at":"2024-11-24T16:35:33.347Z","updated_at":"2025-04-10T22:53:16.487Z","avatar_url":"https://github.com/thasmo.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# External SVG Polyfill [![npm][npm-badge]][npm] [![CDN][cdn-badge]][cdn]\n\u003e Small and basic polyfill to support referencing [external SVG files](https://css-tricks.com/svg-use-external-source/)\n\nBrowser like `IE9-IE11`, `Edge12`, `Safari 5.1-6`, or `UCWeb11`\n[do not support referencing external files](https://caniuse.com/#feat=svg) via location hash.\nReferencing external files can be especially useful when dealing with a technique called\n*SVG sprites*, where multiple SVG elements are stored within a single SVG file. It is possible\nto inline these *SVG sprites* into the HTML document itself, but this has several disadvantages\ni.e. caching issues, unneeded HTML file size growth, development inconveniences, etc.\nExternally referenced *SVG sprites* mitigate those problems but are not supported in the mentioned browsers.\n\n**`external-svg-polyfill` embeds referenced SVG files automatically.**\n\n**Features**\n* User-agent sniffing is used to determine feature support.\n* External SVG files are fetched via `xhr` and embedded while `use` elements are updated.\n* Cross-domain SVG files are fetched and embedded for all browsers to work around browser limitations.\n* To prevent naming collision issues, `id` attributes are updated to use a unique name.\n* Dynamically added SVG `use` elements are processed upon changes in the `DOM`.\n* Various lifecycle events get dispatched on relevant `DOM` elements.\n* Minified file size is below 5 KiB to keep the load, parse and execution times low.\n* Script is not self-executing, it needs to be called explicitly.\n* Project is written in TypeScript.\n\n## Setup\n\n### Installation\n\n[**npm**][npm]\n```sh\nnpm install @thasmo/external-svg-polyfill\n```\n\n[**CDN**][cdn]\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/@thasmo/external-svg-polyfill@3/browser/bundle.min.js\"\u003e\u003c/script\u003e\n```\n\n## Usage\n\nJust define some `svg use` elements in the HTML markup and let `external-svg-polyfill` do the rest.\n\n**Static Website**\n```html\n\u003c!doctype html\u003e\n\u003chtml\u003e\n    \u003chead\u003e\n        \u003cscript src=\"https://cdn.jsdelivr.net/npm/@thasmo/external-svg-polyfill@2/browser/bundle.min.js\"\u003e\u003c/script\u003e\n        \u003cscript\u003e\n            window.document.addEventListener('DOMContentLoaded', function() {\n                new ExternalSvgPolyfill();\n            });\n        \u003c/script\u003e\n    \u003c/head\u003e\n    \u003cbody\u003e\n        \u003csvg xmlns=\"http://www.w3.org/2000/svg\"\u003e\n            \u003cuse href=\"/static/sprite.svg#icon\"\u003e\u003c/use\u003e\n        \u003c/svg\u003e\n    \u003c/body\u003e\n\u003c/html\u003e\n```\n\n**Web Application**\n```js\nimport ExternalSvgPolyfill from '@thasmo/external-svg-polyfill';\nnew ExternalSvgPolyfill();\n```\n\n### API\n\n| method | description |\n|--------|-------------|\n| **run** | *Run the polyfill manually if the `run` option is set to `false`.* |\n| **observe** | *Start observing the DOM for changes if the `observe` option is set to `false`.* |\n| **unobserve** | *Stop observing the DOM for changes.* |\n| **destroy** | *Stop the polyfill, stop observing and restore the original markup.* |\n| **detect** | *Run browser detection manually if the `detect` option is set to `false`.* |\n\n### Options\n\n| option | description | type | default |\n|--------|-------------|------|---------|\n| **target** | *SVG `use` elements to process.* | `string`, `SVGUseElement[]`, `NodeListOf\u003cSVGUseElement\u003e` | `svg use` |\n| **context** | *Element within to search for SVG use elements.* | `HTMLElement` | `window.document.body ?: window.document.documentElement` |\n| **root** | *Element to which prepend SVG embeds to.* | `HTMLElement` | `window.document.body ?: window.document.documentElement` |\n| **run** | *Run the polyfill on object instantiation.* | `boolean` | `true` |\n| **prefix** | *Prefix `id` attribute values to ensure uniqueness. `false` won't change the attributes.* | `boolean` | `true` |\n| **detect** | *Detect browser-support automatically. `false` will run the polyfill in any browser.* | `boolean` | `true` |\n| **observe** | *Observe DOM changes within the `context` element and rerun the polyfill.* | `boolean` | `true` |\n| **crossdomain** | *Embed crossdomain SVG files for all browsers regardless.* | `boolean` | `true` |\n| **namespace** | *Namespace of the dispatched events.* | `string` | `external-svg-polyfill` |\n| **agents** | *Array of regular expressions matching relevant user agents to polyfill.* | `RegExp[]` | `[/Edge\\/12/, /Version\\/6\\.0.+Safari/, /UCBrowser\\/11/]` |\n\n### Events\n\nAll event are prefixed with the `namespace` option, are bubbling and can be cancelled using `event.preventDefault()`.\n\n| event | description | data |\n|-------|-------------|------|\n| **`external-svg-polyfill`.load** | *An external SVG file is loaded via `xhr`.* | `address` |\n| **`external-svg-polyfill`.insert** | *An external SVG file is inserted.* | `address`, `file` |\n| **`external-svg-polyfill`.remove** | *An external SVG file is removed.* | `address` |\n| **`external-svg-polyfill`.apply** | *An SVG `use` element's `href` attribute is updated.* | `address`, `identifier` |\n| **`external-svg-polyfill`.revoke** | *An SVG `use` element's `href` attribute is restored.* | `value` |\n\n## Compatibility\n\n`external-svg-polyfill` can polyfill these browsers:\n* `Internet Explorer 11` *tested*\n* `UCWeb 11` *untested*\n\n## Alternatives\n\nSome alternatives exist and, in fact, `external-svg-polyfill` was greatly inspired by them. Check them out!\n\n* [**SVG for Everybody**](https://github.com/jonathantneal/svg4everybody) by [*Jonathan Neal*](https://github.com/jonathantneal)\n* [**svgxuse**](https://github.com/Keyamoon/svgxuse) by [*Keyamoon*](https://github.com/Keyamoon)\n* [**SVG\\\u003cuse\\\u003eIt**](https://github.com/sinnerschrader/svg-use-it) by [*SinnerSchrader*](https://github.com/sinnerschrader)\n* [**SVG Symbols Polyfill**](https://github.com/evan2x/svg-symbols-polyfill) by [*Evan*](https://github.com/evan2x)\n* [**SVGInjector**](https://github.com/iconic/SVGInjector) by [*iconic*](https://github.com/iconic)\n\n## Resources\n\n* [**SVG on the web - A Practical Guide**](https://svgontheweb.com/) by [*Jake Giltsoff*](https://twitter.com/jakegiltsoff)\n* [**SVG use with External Source**](https://css-tricks.com/svg-use-external-source/) by [*Chris Coyier*](https://twitter.com/chriscoyier)\n* [**SVG use with External Reference, Take 2**](https://css-tricks.com/svg-use-with-external-reference-take-2/) by [*Chris Coyier*](https://twitter.com/chriscoyier)\n* [**SVG Sprite Workflow That Works**](https://medium.com/@iamryanyu/svg-sprite-workflow-that-works-f5609d4d6144) by [*Ryan Yu*](https://twitter.com/iamryanyu)\n* [**svgomg**](https://jakearchibald.github.io/svgomg/) by [*Jake Archibald*](https://twitter.com/jaffathecake)\n\n## Credits\n\n* Browser logos from [alrra/browser-logos](https://github.com/alrra/browser-logos)\n* Bundler logos from [gilbarbara/logos](https://github.com/gilbarbara/logos)\n* Browser testing via [browserstack](https://github.com/browserstack)\n\n[![BrowserStack](https://www.browserstack.com/images/mail/browserstack-logo-footer.png)](https://www.browserstack.com/)  \n[**BrowserStack**](https://www.browserstack.com/) loves open source and provides free manual and automated testing for this project! ❤️\n\n## License\n\n[MIT license](LICENSE.md)\n\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fthasmo%2Fexternal-svg-polyfill.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fthasmo%2Fexternal-svg-polyfill?ref=badge_large)\n\n---\n\n[![forthebadge](https://forthebadge.com/images/badges/built-with-love.svg)](https://forthebadge.com)\n\n[npm]: https://www.npmjs.com/package/@thasmo/external-svg-polyfill\n[npm-badge]: https://img.shields.io/npm/v/@thasmo/external-svg-polyfill.svg\n[cdn]: https://www.jsdelivr.com/package/npm/@thasmo/external-svg-polyfill\n[cdn-badge]: https://data.jsdelivr.com/v1/package/npm/@thasmo/external-svg-polyfill/badge?style=rounded\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthasmo%2Fexternal-svg-polyfill","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthasmo%2Fexternal-svg-polyfill","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthasmo%2Fexternal-svg-polyfill/lists"}