This plugin simplifies the process of using SVG sprites within your SvelteKit projects. It compiles your SVG files into a single sprite, optimizing them with SVGO, and injects the sprite directly into your application's HTML.
app.html
file for streamlined integration.Build sprite from folder
Style id encapsulating
Generate a single SVG sprite file.
Remove injectLabel
option.
Add outputFile
option.
Add watch for svgSource
change.
Reload the page when the sprite file is generated.
Build sprite from files array
Error handling
Save sprite to file
Unwrap symbols from file in folder
Add svg's from @import
1. Install the Plugin:
Run the following command in your SvelteKit project:
npm install -D sveltekit-sprite
2. Configure Vite:
Import and configure the plugin in your vite.config.js
file:
import { sveltekit } from '@sveltejs/kit/vite';
import { sveltekitSprite } from 'sveltekit-sprite';
/** @type {import('vite').UserConfig} */
const config = {
plugins: [
sveltekit(),
sveltekitSprite({
// Options go here (see below)
}),
],
};
export default config;
3. Place SVG Files:
Place your SVG files within a designated source directory. The default location is src/lib/sprite
, but this can be customized using the svgSource
option.
4. Integrate the Sprite into Your App (using hooks.server.ts
):
To integrate the SVG sprite with your application you have to:
Add label to app template:
In app.html
add label %vite.plugin.sprite%
to point Vite where to inline the svg sprite.
<body data-sveltekit-preload-data="hover">
%vite.plugin.sprite%
<div style="display: contents">%sveltekit.body%</div>
</body>
Create or update src/hooks.server.ts
file.
import { sequence } from '@sveltejs/kit/hooks';
import svgSprite from '$lib/sveltekit-sprite.svg?raw';
const handleSvgSprite: Handle = async ({ event, resolve }) => {
return resolve(event, {
transformPageChunk: ({ html }) => html.replace('%vite.plugin.sprite%', svgSprite ?? '')
});
};
export const handle: Handle = sequence(handleSvgSprite);
5. Add Links to SVG Symbols:
Reference the specific symbols in your Svelte components using the following format:
<svg>
<use xlink:href="#[symbolPrefix]--[subfolder]-[file-name]" />
</svg>
[symbolPrefix]
is the value you set for the symbolPrefix
option (defaults to svg
).[subfolder]
is the name of the subfolder (if any) where your SVG file is located within the svgSource
directory. Use empty string if no subfolders.[file-name]
is the name of your SVG file (without the .svg
extension).Example:
If you have an SVG file named star.svg
located in src/lib/sprite/icons/
, and you're using the default symbolPrefix
, the ID would be #svg--icons-star
.
Here's a breakdown of the available options:
svgSource
string
'src/lib/sprite'
sveltekitSprite({
svgSource: 'src/assets/svg',
});
outputFile
string
'src/lib/sveltekit-sprite.svg'
hooks.server.ts
file, as shown in the Get Started section.sveltekitSprite({
outputFile: 'static/sprite.svg', // Place in the static folder for direct access
});
symbolPrefix
string
'svg'
sveltekitSprite({
symbolPrefix: 'icon',
});
Usage in Svelte:
<svg>
<use xlink:href="#icon--icons-star" />
</svg>
stylePrefix
string
'icon'
sveltekitSprite({
stylePrefix: 'icon-style',
});
svgoOptions
Type: object
Default: { presetDefault: true }
Description: Configuration options for the SVGO optimizer. Refer to the SVGO documentation for a comprehensive list of available options.
presetDefault
: Enables or disables SVGO's default plugins.sveltekitSprite({
svgoOptions: {
presetDefault: true, // or false to disable default plugins
plugins: [
{ name: 'removeViewBox', active: false }, // Disable removeViewBox
{ name: 'removeAttrs', params: { attrs: ['fill', 'stroke'] } }, // Remove fill and stroke attributes
],
},
});
⚠️ Important Notes about svgoOptions
:
presetDefault
to false
, you'll typically want to specify the plugins
option to configure the optimizations you want to apply. Otherwise, no optimizations will occur.removeViewBox: false
option.prefixIds
option is always on for build a sprite from a folder with the: prefix
option, you can't override it.While primarily designed for SvelteKit, you can potentially integrate the sprite into a standard Svelte project (not tested):
npm install -D sveltekit-sprite
vite.config.js
.<script>
import svgSprite from '$lib/sveltekit-sprite.svg?raw';
</script>
<div>{@html svgSprite}</div>