external-svg-loader
Advanced tools
SVGs from an external source can be rendered with <img> tags, but this has multiple drawbacks: you can't customize the fill or stroke colors, use CSS variables, or use focus/hover states.
SVG 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.
It's super-tiny, works with all frameworks, requires no additional code except the initial script load, and has minimal to no impact on performance.
SVG 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:
<!--
Include this script anywhere in your code, preferably <HEAD> so
icons can be fetched faster.
-->
<script type="text/javascript" src="svg-loader.min.js" async></script>
<!-- Use an external SVG -->
<svg
data-src="https://unpkg.com/@mdi/svg@5.9.55/svg/star.svg"
width="50"
height="50"
fill="red"></svg>
<svg
data-src="https://unpkg.com/@mdi/svg@5.9.55/svg/heart.svg"
width="50"
height="50"
fill="red"></svg>
<svg
data-src="https://unpkg.com/@mdi/svg@5.9.55/svg/cog.svg"
width="50"
height="50"
fill="currentColor"
style="color: purple;"></svg>
Note: Because SVG Loader fetches file using XHRs, it's limited by CORS policies of the browser.
So 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.
The library is framework/platform agnostic. You should be able to use it in React, Vue.js and others as long as you're using the correct attributes.
npm install external-svg-loader
Then, in your app, require/import external-svg-loader anywhere. Here's an example:
import React from "react";
import ReactDOM from "react-dom";
import "external-svg-loader";
class App extends React.Component {
render() {
return (
<svg
data-src="https://s2.svgbox.net/materialui.svg?ic=mail"
fill="currentColor"
width="50px"
height="50px"
style={{
color: "red"
}}
/>
);
}
}
ReactDOM.render(<App />, document.getElementById("container"));
SVG loader can also be included via unpkg CDN. Example:
<script
type="text/javascript"
src="https://unpkg.com/external-svg-loader@latest/svg-loader.min.js"
async></script>
By 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".
You can destroy the currently stored cache by calling:
SVGLoader.destroyCache();
You can also modify the caching period by passing number of seconds. Example:
<svg
data-src="https://unpkg.com/@mdi/svg@5.9.55/svg/heart.svg"
data-cache="604800"
width="50"
height="50"></svg>
<svg
data-src="https://unpkg.com/@mdi/svg@5.9.55/svg/heart.svg"
data-cache="21600"
width="50"
height="50"></svg>
<svg
data-src="https://unpkg.com/@mdi/svg@5.9.55/svg/heart.svg"
data-cache="disabled"
width="50"
height="50"></svg>
SVG format supports scripting. However, for security reasons, svg-loader will strip all JS code before injecting the SVG file. You can enable it by:
<svg
data-src="https://unpkg.com/@mdi/svg@5.9.55/svg/heart.svg"
data-js="enabled"
onclick="alert('clicked')"
width="50"
height="50"
fill="red"></svg>
To prevent conflicts between conflicting identifiers of different SVGs, svg-loader scopes the identifiers and styling rules by adding prefixes.
You can disable this behavior by:
<svg
data-src="https://unpkg.com/@mdi/svg@5.9.55/svg/heart.svg"
data-unique-ids="disabled"
width="50"
height="50"
fill="red"></svg>
<svg
data-src="https://unpkg.com/@mdi/svg@5.9.55/svg/heart.svg"
data-css-scoping="disabled"
width="50"
height="50"
fill="red"></svg>
You 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.
<svg
data-src="https://unpkg.com/@mdi/svg@5.9.55/svg/heart.svg"
data-loading="lazy"
width="50"
height="50"></svg>
When 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.
oniconload inline function<svg
data-src="https://unpkg.com/@mdi/svg@5.9.55/svg/cog.svg"
oniconload="console.log('Icon loaded', this)"></svg>
<svg data-src="https://unpkg.com/@mdi/svg@5.9.55/svg/cog.svg"></svg>
<script>
window.addEventListener('iconload', (e) => {
if (e.target.id === 'iconload') {
console.log('Icon loaded', e.target);
}
});
</script>
iconloaderror eventWhen an error occurs during loading of the SVG file, an iconloaderror event is triggered, passing the error message as the event's detail.
<svg data-src="https://unpkg.com/@mdi/svg@5.9.55/svg/this-svg-does-not-exist.svg"></svg>
<script>
window.addEventListener('iconloaderror', (e) => {
console.error('Failed to load SVG:', e.detail);
});
</script>
Similarly 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):
<svg
data-src="https://unpkg.com/@mdi/svg@5.9.55/svg/cog.svg"
oniconloaderror="console.log('Error loading SVG:', error.toString())"></svg>
React doesn't support custom events out of the box. To circumvent this limitation, you can use refs.
class MyApp extends React.Component {
constructor(props) {
super(props);
this.ref = React.createRef()
}
render() {
return (<svg data-src="https://unpkg.com/@mdi/svg@5.9.55/svg/cog.svg" ref={this.ref}></svg>);
}
componentDidMount() {
this.ref.current.addEventListener('iconload', () => {
console.log("Icon Loaded", this.ref.current)
});
this.ref.current.addEventListener('iconloaderror', (e) => {
console.error('Failed to load SVG:', e.detail);
});
}
}
MIT
FAQs
Plug 'n play external SVG loader
The npm package external-svg-loader receives a total of 13,198 weekly downloads. As such, external-svg-loader popularity was classified as popular.
We found that external-svg-loader demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Four npm packages disguised as cryptographic tools steal developer credentials and send them to attacker-controlled Telegram infrastructure.
Security News
Ruby maintainers from Bundler and rbenv teams are building rv to bring Python uv's speed and unified tooling approach to Ruby development.
Security News
Following last week’s supply chain attack, Nx published findings on the GitHub Actions exploit and moved npm publishing to Trusted Publishers.