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.
- SVG Sprite Generation: Creates a single SVG sprite containing symbols derived from your source SVG files.
- Optimized with SVGO: Applies SVGO (Scalable Vector Graphics Optimizer) to reduce file size and improve performance. Includes options to customize optimization.
- Unique Symbol IDs: Generates unique IDs for all symbols within the sprite, ensuring proper referencing.
- Folder-Based IDs: Supports folder-based organization of your SVG files, reflecting in the symbol IDs for easy referencing.
- Direct HTML Injection: Injects the generated sprite directly into your application's
app.htmlfile for streamlined integration. - File Watcher: Watches for changes in your SVG source directory and automatically regenerates the sprite during development.
- Style Prefix: Replace all id's inside the svg files to be more specific to your project
-
Build sprite from folder
-
Style id encapsulating
-
Generate a single SVG sprite file.
-
Remove
injectLabeloption. -
Add
outputFileoption. -
Add watch for
svgSourcechange. -
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-sprite2. 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.htmladd 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.tsfile.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 thesymbolPrefixoption (defaults tosvg).[subfolder]is the name of the subfolder (if any) where your SVG file is located within thesvgSourcedirectory. Use empty string if no subfolders.[file-name]is the name of your SVG file (without the.svgextension).
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:
- Type:
string - Default:
'src/lib/sprite' - Description: Specifies the directory where your SVG source files are located (relative to your project root). The plugin watches this folder for changes.
sveltekitSprite({
svgSource: 'src/assets/svg',
});- Type:
string - Default:
'src/lib/sveltekit-sprite.svg' - Description: Specifies the output file where the generated SVG sprite will be saved. This file is then imported and used in your
hooks.server.tsfile, as shown in the Get Started section.
sveltekitSprite({
outputFile: 'static/sprite.svg', // Place in the static folder for direct access
});- Type:
string - Default:
'svg' - Description: The prefix to be added to the beginning of each symbol ID in the sprite. This helps you uniquely identify your SVG symbols.
sveltekitSprite({
symbolPrefix: 'icon',
});Usage in Svelte:
<svg>
<use xlink:href="#icon--icons-star" />
</svg>- Type:
string - Default:
'icon' - Description: The prefix to be added to all IDs inside the svg files to be more specific to your project.
sveltekitSprite({
stylePrefix: 'icon-style',
});-
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.- You can override 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
],
},
});svgoOptions:
- If you set
presetDefaulttofalse, you'll typically want to specify thepluginsoption to configure the optimizations you want to apply. Otherwise, no optimizations will occur. - For building the sprite from folder the plugin add
removeViewBox: falseoption. prefixIdsoption is always on for build a sprite from a folder with the:prefixoption, you can't override it.
While primarily designed for SvelteKit, you can potentially integrate the sprite into a standard Svelte project (not tested):
- Install the Plugin:
npm install -D sveltekit-sprite - Configure Vite: Configure the plugin inside
vite.config.js. - Import the Sprite:
<script> import svgSprite from '$lib/sveltekit-sprite.svg?raw'; </script> <div>{@html svgSprite}</div>
- Add Links: follow 5. Add Links to SVG Symbols: section to implement symbols in your project