@marmot-webdev/sprite-loader v1.0.0
sprite-loader
sprite-loader is a small, standalone JavaScript module that loads SVG sprites asynchronously and stores them in the browser's local storage. This enables the sprites to be reused across multiple pages without making additional server requests, which can improve the performance and user experience of your website.
Installation
To install sprite-loader, use the following command:
npm install @marmot-webdev/sprite-loaderAlternatively, you can include the sprite-loader.min.js script in your HTML:
<script src="path/to/sprite-loader.min.js"></script>Usage
Basic example
import SpriteLoader from '@marmot-webdev/sprite-loader';
const spriteLoader = new SpriteLoader({
sprites: {
global: ['core.svg', 'flags.svg'].map(name => ({ basename: name }))
},
dirname: 'assets/sprites/'
});Advanced example
import SpriteLoader from '@marmot-webdev/sprite-loader';
const spriteLoader = new SpriteLoader({
sprites: {
global: [
{
root: 'https://cdn.example.com/',
dirname: 'path/to/sprite/',
basename: 'core.svg?v=1.0'
},
{
basename: 'flags.svg',
prefix: 'xyz-',
onload(spriteURL) {
console.log(`The sprite "flags.svg" has been loaded from ${spriteURL.href}.`);
}
}
],
local: [
{
basename: 'contacts.svg'
}
]
},
dirname: 'assets/sprites/',
prefix: 'abc-'
});Options
The available options are:
{
container: null,
extractor: null,
sprites: {
global: [],
local: []
},
root: '',
dirname: '',
extname: '.svg',
prefix: '',
onload: null
}sprites.global
Type: array\
Default: []
An array of objects representing the sprites that are available for all pages. Each object should have the property basename (the name of a sprite). The optional properties may include root, dirname, extname, prefix, and onload, and if they are provided, they take precedence over the corresponding general options.
sprites.local
Type: array\
Default: []
An array of objects representing the sprites that are available for specific pages. In order for the script to know which sprites to load from this array, the page must have a data-sprites attribute that includes a list of sprite names. You can refer to the extractor option for more details.
The rest of the description is identical to the sprites.global property.
root
Type: string\
Default: ''
The root URL to use when loading the sprite. If you're hosting your files on a Content Delivery Network (CDN), you can set the root property to the base URL of the CDN. Defaults to document.baseURI.
dirname
Type: string\
Default: ''
A directory containing the sprites.
extname
Type: string\
Default: '.svg'
The extname property is used to specify the file extension of a sprite. In theory, you can load any type of text file, not just sprites.
prefix
Type: string\
Default: ''
A string that is prepended to the sprite's basename to create a unique key for caching the sprite content in local storage.
container
Type: function\
Default: null
A function that returns the container element to use for the sprites. Defaults to a function that creates a <div> element and prepends it to the document body.
Note: You may want to override it if your icons contain gradients.
An example of a custom implementation:
container: () => document.querySelector('#sprite-container')extractor
Type: function\
Default: null
A function that extracts the names of the local sprites that will be used. Defaults to a function that searches for a data-sprites attribute on the <html> element. The attribute's value is then split by | to extract the sprite names.
<html data-sprites="categories|contacts">...</html>An example of your own implementation:
<html data-sprites='["categories", "contacts"]'>...</html>extractor: () => {
try {
return JSON.parse(document.documentElement.dataset.sprites);
} catch (e) {
return [];
}
}onload
Type: function\
Default: null
A callback function that is called after all sprites have been loaded and inserted into the DOM.
Copyright and license
Copyright (c) 2023—present, Serhii Babakov.
The library is licensed under The MIT License.
1 year ago