{"id":15297170,"url":"https://github.com/shubhamjain/svg-loader","last_synced_at":"2025-04-13T02:18:52.158Z","repository":{"id":37422952,"uuid":"314598487","full_name":"shubhamjain/svg-loader","owner":"shubhamjain","description":"Plug 'n Play external SVG loader","archived":false,"fork":false,"pushed_at":"2024-07-13T21:28:02.000Z","size":291,"stargazers_count":202,"open_issues_count":5,"forks_count":24,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-04T04:09:09.198Z","etag":null,"topics":["css","html","svg"],"latest_commit_sha":null,"homepage":"","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/shubhamjain.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}},"created_at":"2020-11-20T15:47:31.000Z","updated_at":"2025-03-20T03:20:31.000Z","dependencies_parsed_at":"2024-06-18T14:01:51.290Z","dependency_job_id":"c9dbe8b8-9aec-4363-93aa-f76360814848","html_url":"https://github.com/shubhamjain/svg-loader","commit_stats":{"total_commits":106,"total_committers":10,"mean_commits":10.6,"dds":"0.21698113207547165","last_synced_commit":"b7920683cb718cb4b5fcfa82cda51fd1344257c3"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shubhamjain%2Fsvg-loader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shubhamjain%2Fsvg-loader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shubhamjain%2Fsvg-loader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shubhamjain%2Fsvg-loader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shubhamjain","download_url":"https://codeload.github.com/shubhamjain/svg-loader/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248654236,"owners_count":21140266,"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":["css","html","svg"],"created_at":"2024-09-30T19:15:29.207Z","updated_at":"2025-04-13T02:18:52.130Z","avatar_url":"https://github.com/shubhamjain.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SVG Loader\n[![NPM](https://img.shields.io/npm/v/external-svg-loader.svg)](https://www.npmjs.com/package/external-svg-loader)\n![minified size](http://img.badgesize.io/shubhamjain/svg-loader/master/svg-loader.min.js?label=minified%20size\u0026v=10) ![gzip size](http://img.badgesize.io/shubhamjain/svg-loader/master/svg-loader.min.js?compression=gzip\u0026v=10)\n\nSVGs from an external source can be rendered with `\u003cimg\u003e` tags, but this has multiple drawbacks: you can't customize the fill or stroke colors, use CSS variables, or use focus/hover states.\n\nSVG Loader is a simple JS library that fetches SVGs using XHR and injects the SVG code in the tag's place. This lets you use externally stored SVGs (e.g, on CDN) just like inline SVGs.\n\nIt's super-tiny, works with all frameworks, requires no additional code except the initial script load, and has minimal to no impact on performance.\n\n[**Demo →**](https://codepen.io/shubhamjainco/pen/rNyBVmY)\n\n## How to Use?\nSVG Loader is designed to be plug and play. Hence, all you need to is to include the loader JS anywhere in your code, and then start using the code like this:\n\n### Download and Include\n\n```html\n\u003c!-- \n    Include this script anywhere in your code, preferably \u003cHEAD\u003e so\n    icons can be fetched faster.\n--\u003e\n\u003cscript type=\"text/javascript\" src=\"svg-loader.min.js\" async\u003e\u003c/script\u003e\n\n\u003c!-- Use an external SVG --\u003e\n\u003csvg\n  data-src=\"https://unpkg.com/@mdi/svg@5.9.55/svg/star.svg\"\n  width=\"50\"\n  height=\"50\"\n  fill=\"red\"\u003e\u003c/svg\u003e\n\u003csvg\n  data-src=\"https://unpkg.com/@mdi/svg@5.9.55/svg/heart.svg\"\n  width=\"50\"\n  height=\"50\"\n  fill=\"red\"\u003e\u003c/svg\u003e\n\n\u003csvg\n  data-src=\"https://unpkg.com/@mdi/svg@5.9.55/svg/cog.svg\"\n  width=\"50\"\n  height=\"50\"\n  fill=\"currentColor\"\n  style=\"color: purple;\"\u003e\u003c/svg\u003e\n```\n\n[**See Here →**](https://codepen.io/shubhamjainco/pen/jOBEgPY)\n\n**Note**: Because SVG Loader fetches file using XHRs, it's limited by CORS policies of the browser. \nSo you need to ensure that correct `Access-Control-Allow-Origin` headers are sent with the file being served or that the files are hosted on your own domain. \n\n\n### Or, use from the npm package\nThe library is framework/platform agnostic. You should be able to use it in React, Vue.js and others\nas long as you're using the correct attributes.\n\n\n```\nnpm install external-svg-loader\n```\n\nThen, in your app, require/import `external-svg-loader` anywhere. Here's an example:\n\n```jsx\nimport React from \"react\";\nimport ReactDOM from \"react-dom\";\n\nimport \"external-svg-loader\";\n\nclass App extends React.Component {\n  render() {\n    return (\n      \u003csvg\n        data-src=\"https://s2.svgbox.net/materialui.svg?ic=mail\"\n        fill=\"currentColor\"\n        width=\"50px\"\n        height=\"50px\"\n        style={{\n          color: \"red\"\n        }}\n      /\u003e\n    );\n  }\n}\n\nReactDOM.render(\u003cApp /\u003e, document.getElementById(\"container\"));\n```\n\n[**See Here →**](https://codesandbox.io/s/react-playground-forked-x7w1l?file=/index.js)\n\n### Or, use a CDN\nSVG loader can also be included via unpkg CDN. Example:\n\n```html\n\u003cscript\n    type=\"text/javascript\"\n    src=\"https://unpkg.com/external-svg-loader@latest/svg-loader.min.js\"\n    async\u003e\u003c/script\u003e\n```\n\n## Configuration\n\n### 1. Disable/Modify Caching\nBy default, the XHR response is cached for 30 days, so that any subsequent loads are instantenous. You can disable this behavior by passing `data-cache=\"disabled\"`. \n\nYou can destroy the currently stored cache by calling:\n\n```js\nSVGLoader.destroyCache();\n```\n\nYou can also modify the caching period by passing number of seconds. Example:\n\n#### Cache for a week\n```html\n\u003csvg\n  data-src=\"https://unpkg.com/@mdi/svg@5.9.55/svg/heart.svg\"\n  data-cache=\"604800\"\n  width=\"50\"\n  height=\"50\"\u003e\u003c/svg\u003e\n```\n\n#### Cache for a six hours\n```html\n\u003csvg\n  data-src=\"https://unpkg.com/@mdi/svg@5.9.55/svg/heart.svg\"\n  data-cache=\"21600\"\n  width=\"50\"\n  height=\"50\"\u003e\u003c/svg\u003e\n```\n\n#### Disable Caching\n```html\n\u003csvg\n  data-src=\"https://unpkg.com/@mdi/svg@5.9.55/svg/heart.svg\"\n  data-cache=\"disabled\"\n  width=\"50\"\n  height=\"50\"\u003e\u003c/svg\u003e\n```\n\n### 2. Enable Javascript\nSVG format supports scripting. However, for security reasons, svg-loader will strip all JS code before injecting the SVG file.\nYou can enable it by: \n\n```html\n\u003csvg\n  data-src=\"https://unpkg.com/@mdi/svg@5.9.55/svg/heart.svg\"\n  data-js=\"enabled\"\n  onclick=\"alert('clicked')\"\n  width=\"50\"\n  height=\"50\"\n  fill=\"red\"\u003e\u003c/svg\u003e\n```\n\n### 3. Disable Unique IDs, Styling\nTo prevent conflicts between conflicting identifiers of different SVGs, svg-loader scopes the identifiers and styling rules by adding prefixes. \n\nYou can disable this behavior by:\n\n#### Disable Unique IDs\n\n```html\n\u003csvg\n  data-src=\"https://unpkg.com/@mdi/svg@5.9.55/svg/heart.svg\"\n  data-unique-ids=\"disabled\"\n  width=\"50\"\n  height=\"50\"\n  fill=\"red\"\u003e\u003c/svg\u003e\n```\n\n#### Disable CSS Scoping\n\n```html\n\u003csvg\n  data-src=\"https://unpkg.com/@mdi/svg@5.9.55/svg/heart.svg\"\n  data-css-scoping=\"disabled\"\n  width=\"50\"\n  height=\"50\"\n  fill=\"red\"\u003e\u003c/svg\u003e\n```\n\n## Lazy Loading\nYou can also lazy load icons by using `data-loading=lazy`. This will make icon not load until it's about to enter the viewport. For lazy loading, `external-svg-loader` uses [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API).\n\n```html\n\u003csvg\n  data-src=\"https://unpkg.com/@mdi/svg@5.9.55/svg/heart.svg\"\n  data-loading=\"lazy\"\n  width=\"50\"\n  height=\"50\"\u003e\u003c/svg\u003e\n```\n\n## Event\nWhen the SVG has been loaded an event `iconload` is triggered. This can be used to get the references to the loaded SVG element and do some further processing. You can also use the `oniconload` inline function. \n\n### Using `oniconload` inline function\n```html\n\u003csvg\n  data-src=\"https://unpkg.com/@mdi/svg@5.9.55/svg/cog.svg\"\n  oniconload=\"console.log('Icon loaded', this)\"\u003e\u003c/svg\u003e\n```\n\n### Using addEventListener\n```html\n\u003csvg data-src=\"https://unpkg.com/@mdi/svg@5.9.55/svg/cog.svg\"\u003e\u003c/svg\u003e\n\n\u003cscript\u003e\n  window.addEventListener('iconload', (e) =\u003e {\n      if (e.target.id === 'iconload') {\n        console.log('Icon loaded', e.target);\n      }\n  });\n\u003c/script\u003e\n```\n\n### Using the `iconloaderror` event\nWhen an error occurs during loading of the SVG file, an `iconloaderror` event is triggered, passing the error message as the event's `detail`.\n\n```html\n\u003csvg data-src=\"https://unpkg.com/@mdi/svg@5.9.55/svg/this-svg-does-not-exist.svg\"\u003e\u003c/svg\u003e\n\n\u003cscript\u003e\n  window.addEventListener('iconloaderror', (e) =\u003e {\n    console.error('Failed to load SVG:', e.detail);\n  });\n\u003c/script\u003e\n```\n\nSimilarly to the `iconload` event, `iconloaderror` can also be used with an inline function, which will have access to an `error` argument (the `Error` object that was thrown):\n```html\n\u003csvg\n  data-src=\"https://unpkg.com/@mdi/svg@5.9.55/svg/cog.svg\"\n  oniconloaderror=\"console.log('Error loading SVG:', error.toString())\"\u003e\u003c/svg\u003e\n```\n\n### Using Events in React\nReact doesn't support custom events out of the box. To circumvent this limitation, you can use [refs](https://reactjs.org/docs/refs-and-the-dom.html).\n\n```jsx\nclass MyApp extends React.Component {\n  constructor(props) {\n    super(props);\n    this.ref = React.createRef()\n  }\n  render() {\n    return (\u003csvg data-src=\"https://unpkg.com/@mdi/svg@5.9.55/svg/cog.svg\" ref={this.ref}\u003e\u003c/svg\u003e);\n  }\n  componentDidMount() {\n    this.ref.current.addEventListener('iconload', () =\u003e {\n      console.log(\"Icon Loaded\", this.ref.current)\n    });\n    this.ref.current.addEventListener('iconloaderror', (e) =\u003e {\n      console.error('Failed to load SVG:', e.detail);\n    });\n  }\n}\n```\n\n## LICENSE\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshubhamjain%2Fsvg-loader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshubhamjain%2Fsvg-loader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshubhamjain%2Fsvg-loader/lists"}