Nuxt SVG Icon Sprite

An easy and performant way to use SVG icons in your Nuxt 3 app.

Automatically creates SVG <symbol> sprites during the build and provides components and composables to use these icons.

• Aggregate all SVG files into one or more sprite files
• Reduce bundle size and SSR-rendered page size
• Full HMR support
• Provides <SpriteSymbol> component to render <svg> with <use>
• Provides <SpriteSymbolInline> component to inline the SVG
• Loads the sprite.svg from URL (/_nuxt/sprite.svg)
• TypeScript type checking for available symbols

Install

1npm install --save nuxt-svg-icon-sprite

1export default defineNuxtConfig({
2  modules: ['nuxt-svg-icon-sprite'],
3
4  svgIconSprite: {
5    sprites: {
6      default: {
7        importPatterns: ['./assets/icons/**/*.svg'],
8      },
9    },
10  },
11})

Usage

Place the icons in the folder defined in nuxt.config.ts. By default, it's ./assets/icons. The name of the SVG file determines the symbol name.

NOTE: Each symbol in a sprite must have a unique name!

So, if you have a file in ./assets/icons/user.svg, the sprite will contain a <symbol> with the id user.

You can now use the symbol with the provided component:

1<SpriteSymbol name="user" />

This will render the following markup:

1<svg>
2  <use xlink:href="/_nuxt/sprite.svg#user"></use>
3</svg>

The symbol is referenced from the sprite via URL.

Multiple Sprites

If you have a lot of icons, it might make sense to split them into separate sprites.

A typical example would be to have SVGs that appear on every page (navbar, logo, footer, etc.) in the "default" sprite and put page-specific SVGs in separate sprites.

To create an additional sprite, just define a new property on the sprites config object:

1export default defineNuxtConfig({
2  modules: ['nuxt-svg-icon-sprite'],
3
4  svgIconSprite: {
5    sprites: {
6      default: {
7        importPatterns: ['./assets/icons/**/*.svg'],
8      },
9      dashboard: {
10        importPatterns: ['./assets/icons-dashboard/**/*.svg'],
11      },
12    },
13  },
14})

Assuming you have this file ~/assets/icons-dashboard/billing.svg, you can reference it like this:

1<SpriteSymbol name="dashboard/billing" />

The symbol name is prefixed by the name of the sprite (e.g., the key used in the sprites config). The default sprite is always unprefixed.

<SpriteSymbol> component

In addition to the name prop, you can optionally pass the noWrapper prop to only render the <use> tag:

1<SpriteSymbol name="dashboard/billing" :no-wrapper="true" />

This will render the following markup:

1<use xlink:href="/_nuxt/sprite-dashboard.svg#billing"></use>

This is useful if you want to render multiple symbols in one <svg> tag.

You may also use the <SpriteSymbolInline /> component to render the SVG content directly instead of rendering the <use> tag. Note that this will load the entire sprite, not just the symbol to be inlined.

1<SpriteSymbolInline name="search" />

This will render the contents of the SVG file as-is, without any wrapper.

useSpriteData() composable

Get information about the generated sprites and their symbols during runtime.

Useful if you want to render a list of all symbols in a style guide:

1<template>
2  <SpriteSymbol v-for="symbol in symbols" :key="symbol" :name="symbol" />
3</template>
4
5<script setup lang="ts">
6const { symbols } = useSpriteData()
7</script>

Processing SVG Files

By default, the collected SVG symbols are used as-is, including any attributes such as width or height. You can optionally provide processors to alter the parsed SVG before it is added to the sprite.

The module exports a few processors you can use:

1import { removeSizes, forceCurrentColor } from 'nuxt-svg-icon-sprite/processors'
2
3export default defineNuxtConfig({
4  modules: ['nuxt-svg-icon-sprite'],
5
6  svgIconSprite: {
7    sprites: {
8      default: {
9        importPatterns: ['./assets/icons/**/*.svg'],
10        processSpriteSymbol: [removeSizes(), forceCurrentColor()],
11      },
12    },
13  },
14})

removeSizes()

This processor will remove width and height attributes on the <svg> tag.

forceCurrentColor()

This processor will replace all fill and stroke attribute values with currentColor. If you still want to keep some stroke or fill attributes, you can add a data-keep-color attribute on them - those will then be skipped.

cssPrefix() (Experimental)

Prefixes all IDs and classes in a SVG, including <style> selectors. Note that it does not prefix other selectors (e.g. path {}) - these will be shared for all symbols in the sprite!

removeTags()

Removes the given tags. For example, to remove all <title> tags from the SVG:

1import { removeTags } from 'nuxt-svg-icon-sprite/processors'
2
3export default defineNuxtConfig({
4  modules: ['nuxt-svg-icon-sprite'],
5
6  svgIconSprite: {
7    sprites: {
8      default: {
9        importPatterns: ['./assets/icons/**/*.svg'],
10        processSpriteSymbol: [removeTags({ tags: ['title'] })],
11      },
12    },
13  },
14})

Custom Processors

You can also provide your own processors as inline methods:

1import { removeSizes, forceCurrentColor } from 'nuxt-svg-icon-sprite/processors'
2
3export default defineNuxtConfig({
4  modules: ['nuxt-svg-icon-sprite'],
5
6  svgIconSprite: {
7    sprites: {
8      default: {
9        importPatterns: ['./assets/icons/**/*.svg'],
10        processSpriteSymbol: [
11          (svg) => {
12            // Removes all <title> tags.
13            const titles = svg.querySelectorAll('title')
14            titles.forEach((title) => title.remove())
15          },
16        ],
17      },
18    },
19  },
20})

Full Module Options

1import type { HTMLElement } from 'node-html-parser'
2
3export default defineNuxtConfig({
4  modules: ['nuxt-svg-icon-sprite'],
5
6  svgIconSprite: {
7    sprites: {
8      default: {
9        importPatterns: ['./assets/icons/**/*.svg'],
10
11        // Directly provide symbol SVG by path.
12        // These are added after the auto imports defined in
13        // `importPatterns`.
14        symbolFiles: {
15          email: '~/node_modules/some_package/assets/icons/email.svg',
16        },
17
18        processSpriteSymbol(svg: HTMLElement) {
19          // Executed for each sprite symbol.
20
21          // Remove width and height attributes from the SVG.
22          svg.removeAttribute('width')
23          svg.removeAttribute('height')
24
25          // Use 'currentColor' for all fills and strokes.
26          const elements = svg.querySelectorAll('*')
27          const attributes = ['stroke', 'fill']
28          elements.forEach((el) => {
29            attributes.forEach((name) => {
30              const value = el.getAttribute(name)
31              if (value) {
32                el.setAttribute(name, 'currentColor')
33              }
34            })
35          })
36        },
37        processSprite(sprite, ctx) {
38          // Executed for each sprite right before it's saved.
39          // Run SVGO or whatever you like.
40          // Markup contains:
41          // <svg>
42          //   <symbol id="user">...</symbol>
43          //   <symbol id="foobar">...</symbol>
44          // </svg>
45          // You can directly manipulate the `sprite` object.
46        },
47      },
48    },
49  },
50})

The options are the same for each key in sprites.