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