nuxt-svg-icons

A module for Nuxt 3 that allows you to use your own SVG icons quickly and enjoyably powered by vite-plugin-svg4vue.

• ✨  Release Notes

Features

• Multiple ways of use.
• Support Optimize svg via SVGO.
• Support using svg as a component, url and raw with query string.
• HMR (You don't have to reset the project to reload the icons)
• Ability to manipulate icons. e.g. using font-size , fill , stroke , fill-opacity, stroke-width and stroke-opacity.
• Icon only loads if used.
• Support Iconfont svg icons

Quick Setup

1. Add nuxt-svg-icons dependency to your project

# Using pnpm
pnpm add -D nuxt-svg-icons

# Using yarn
yarn add --dev nuxt-svg-icons

# Using npm
npm install --save-dev nuxt-svg-icons

2. Add nuxt-svg-icons to the modules section of nuxt.config.ts

export default defineNuxtConfig({
  modules: [
    'nuxt-svg-icons'
    // use inline options
    // [
    //   'nuxt-svg-icons',
    //   {
    //     svg4vue: { assetsDirName: 'assets/icons' }
    //   }
    // ]
  ],
  // custom nuxt-svg-icons options
  nuxtSvgIcons: {
    svg4vue: {
      assetsDirName: 'assets/icons'
    }
  }
})

3. Put your svg icons in ~/assets/icons folder.

TIPS: if you want to use nuxt-svg-icon component to display your svg icons, you must set svg4vue.assetsDirName to assets/icons.

4. Import your svg icon as a Vue Component.

<template>
  <div>
    <VueLogo fill="green" font-size="36" />
    <VueLogoFilled font-size="50" />

    <!-- using nuxt-svg-icon component -->
    <NuxtSvgIcon name="path/to/file" font-size="36" fill="red" />
  </div>
</template>

<script setup lang="ts">
import VueLogo from '~/assets/icons/iconfont/vue-logo.svg?component'
import VueLogoFilled from '~/assets/icons/iconfont/vue-logo-filled.svg?component'
</script>

If you are using TypeScript, nuxt-svg-icons/client can be added to d.ts declaration file.

/// <reference types="nuxt-svg-icons/client" />

That's it! You can now use nuxt-svg-icons in your Nuxt app ✨

TIPS: All svg will be processed by vite-plugin-svg4vue. More build details please see its self!!!

About the global component nuxt-svg-icon

Component properties

Prop name	Default value	Required	Description	Type
name	undefined	true	The value will be based on its own path directory and filename	string
fontSize	undefined	false	The SVG font size. In fact, for the svg node, vite-plugin-svg4vue will set the width value to font-size, remove svg height and set width to 1em, so that the svg size will be responsive and you can manipulate it's size with font-size	string or number
size	undefined	false	Alias of fontSize	string or number
fill	undefined	false	Define the SVG fill value. In terms of internal implementation, vite-plugin-svg4vue will move all path 's fill attribute to its parent node which is svg node when your svg is a monochrome icon	string
color	undefined	false	Alias of fill	string
stroke	undefined	false	Define the SVG stroke value. This allows you to change the color of outline svg which is created by stroke attribute. In terms of internal implementation, vite-plugin-svg4vue will move all path 's stroke attribute to its parent node which is svg node when your svg is a monochrome icon	string
fillOpacity	undefined	false	The svg' s fill-opacity	string
strokeOpacity	undefined	false	The svg' s stroke-opacity	string
strokeWidth	undefined	false	The svg' s stroke-width	string
useOriginalSize	false	false	Whether to use the svg original width and height	boolean

In the project, use <nuxt-svg-icon name="" />, where name is the name of your svg icon from the folder ~/assets/icons

<nuxt-svg-icon name="foo" /> 

Subfolders

If you would like to use some more complicated folder arrangement you will have to use paths from ~/assets/icons

If you have a svg icon in nested directories such as:

📁icons
  └📁admin
  ⠀⠀└ badge.svg
  └📁user
  ⠀⠀└ badge.svg

then the icons's name will be based on its own path directory and filename. Therefore, the icon's name will be:

<nuxt-svg-icon name="admin/badge" /> and <nuxt-svg-icon name="user/badge" />

Options

Key	Default value	Description
svg4vue	{ assetsDirName: 'assets/icons' }	vite-plugin-svg4vue 's Options
enableNuxtSvgIconComponent	true	Whether to enable nuxt-svg-icon component, if set false, The global component nuxt-svg-icon will not be registered

Development

# Install dependencies
pnpm install

# Generate type stubs
pnpm dev:prepare

# Develop with the playground
pnpm dev

# Build the playground
pnpm dev:build

# Run ESLint
pnpm lint

# Run Vitest
pnpm test
pnpm test:watch

# Release new version
npm run release