Skip to content

Latest commit

 

History

History
177 lines (130 loc) · 5.69 KB

README.md

File metadata and controls

177 lines (130 loc) · 5.69 KB
Raw


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.

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
  1. 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'
    }
  }
})
  1. 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.

  1. 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