Nuxt Icon

[![npm version][npm-version-src]][npm-version-href] [![npm downloads][npm-downloads-src]][npm-downloads-href] [![License][license-src]][license-href] [![Nuxt][nuxt-src]][nuxt-href] <a href="https://volta.net/nuxt-modules/icon?utm_source=nuxt_icon_readme"><img src="https://user-images.githubusercontent.com/904724/209143798-32345f6c-3cf8-4e06-9659-f4ace4a6acde.svg" alt="Volta board"></a>

Add 200,000+ ready to use icons to your Nuxt application, based on Iconify.

Features ✨

Nuxt 3 ready
SSR friendly
Support 200,000 open-source vector icons via Iconify
Support both CSS mode / SVG mode
Custom SVG support (via Vue component, or via local SVG files)

[!NOTE] You are viewing the v1.0 version of this module, which is a complete rewrite for a better developer experience and performance. If you are migrating from v0.6, please check this PR for the full list of changes.

Setup ⛓️

Run the following command to add the module to your project:

npx nuxi module add icon

That's it, you can now use the <Icon /> in your components!

✨ If you are using VS Code, you can use the Iconify IntelliSense extension by @antfu

<details> <summary>Manual Setup</summary>

You can install the module manually with:

npm i -D @nuxt/icon

Update your nuxt.config.ts

export default defineNuxtConfig({
  modules: [
    '@nuxt/icon'
  ]
})

If you have the legacy module nuxt-icon installed, you might want to remove it from the modules list.

</details>

Usage 👌

Props:

name (required): icon name or global component name
size: icon size (default: 1em)
mode: icon rendering mode (svg or css, default: css)

Attributes:

When using an icon from Iconify, a <span> or <svg> will be created based on the rendering mode, you can give all the attributes of the native element.

<Icon name="uil:github" style="color: black" />

TailwindCSS v4:

When using TailwindCSS v4 with the css mode, you should configure the cssLayer in Nuxt's app config:

// ~/app.config.ts
export default defineAppConfig({
  icon: {
    mode: 'css',
    cssLayer: 'base'
  }
})

Iconify Dataset

You can use any name from the https://icones.js.org collection:

<Icon name="uil:github" />

It supports the i- prefix (for example, i-uil-github).

It's highly recommended to install the icon data locally with

npm i -D @iconify-json/collection-name

For example, to use the uil:github icon, install its collection with @iconify-json/uil. This way the icons can be served locally or from your serverless functions, which is faster and more reliable on both SSR and client-side.

[!NOTE] You may also know you can install @iconify/json package to include all iconify icons. This is not recommended because it will increase your server bundle size and building performance. If you choose to do so, we'd recommend to explicitly specify the collection names you need:
export default defineNuxtConfig({
  modules: ['@nuxt/icon'],
  icon: {
    serverBundle: {
      collections: ['uil', 'mdi'] // <!--- this
    }
  }
})

Vue Component

When the name matches a global registered component, it will be rendered as that component (in this case mode will be ignored):

<Icon name="MyComponent" />

Note that MyComponent needs to be inside components/global/ folder (see example).

[!TIP] You can also change the component name with:
export default defineNuxtConfig({
  icon: {
    componentName: 'NuxtIcon'
  }
})

Custom Local Collections

You can use local SVG files to create a custom Iconify collection.

For example, place your icons' SVG files under a folder of your choice, for example, ./assets/my-icons:

assets/my-icons
├── foo.svg
├── bar-outline.svg

In your nuxt.config.ts, add an item in icon.customCollections:

export default defineNuxtConfig({
  modules: [
    '@nuxt/icon'
  ],
  icon: {
    customCollections: [
      {
        prefix: 'my-icon',
        dir: './assets/my-icons',
        // if you want to include all the icons in nested directories:
        // recursive: true,
      },
    ],
  },
})

[!NOTE] If you are running on Nuxt 4 with the new app directory, the assets directory is './app/assets/*' instead of './assets/*'.

Then you can use the icons like this:

<template>
  <Icon name="my-icon:foo" />
  <Icon name="my-icon:bar-outline" />
</template>

You can also pass a full custom IconifyJSON object:

export default defineNuxtConfig({
  modules: [
    '@nuxt/icon'
  ],
  icon: {
    customCollections: [
      {
        prefix: 'paid-icons',
        icons: {
          'nuxt': { body: '<path d="M281.44 ... />' },
        },
        width: 512,
        height: 512,
      }
    ],
  },
})

Note that custom local collections require you to have a server to serve the API. When setting ssr: false, or when generating a static app using nuxt generate (which is equivalent to ssr: false), the provider will default to the Iconify API (which does not have your custom icons). If you want to build a SPA with server endpoints, you can explicitly set provider: 'server':

export default defineNuxtConfig({
  modules: [
    '@nuxt/icon'
  ],
  ssr: false,
  icon: {
    provider: 'server', // <-- this
    customCollections: [
      {
        prefix: 'my-icon',
        dir: './assets/my-icons'
      },
    ],
  },
})

Disabling Runtime Fetching

Or if you want to disable the dynamic icon fetching completely and only use icons from the client bundle, you can set provider: 'none':

export default defineNuxtConfig({
  icon: {
    provider: 'none',
    clientBundle: {
      scan: true,
      // ...or other bundle options
    },
  }
})

Case Sensitive Custom Collections

Before v1.10, due to the limitation of Iconify's previous convention, all custom icons were normalized to kebab-case with a warning. Thanks to the updates on Iconify side, starting from v1.10, you can opt-in to use case-sensitive custom collections and by pass the normalization.

export default defineNuxtConfig({
  modules: [
    '@nuxt/icon'
  ],
  icon: {
    customCollections: [
      {
        prefix: 'my-icon',
        dir: './assets/my-icons',
        normalizeIconName: false, // <-- this
      },
    ],
  },
})

Which enable to use assets/my-icons/FooBar.svg as my-icon:FooBar, for example.

normalizeIconName is default to true for backward compatibility, and will be flipped in the future major version. See #265 for more context.

Icon Customization

To update the default size (1em) of the <Icon />, create an app.config.ts with the icon.size property.

Update the default class (.icon) of the <Icon /> with the icon.class property, for a headless Icon, set icon.class: ''`.

You can also define aliases to make swapping out icons easier by leveraging the icon.aliases property.

[!NOTE] Note it's app.config.ts and not nuxt.config.ts for runtime configs.

// app.config.ts
export default defineAppConfig({
  icon: {
    size: '24px', // default <Icon> size applied
    class: 'icon', // default <Icon> class applied
    mode: 'css', // default <Icon> mode applied
    aliases: {
      'nuxt': 'logos:nuxt-icon',
    },
    cssLayer: 'base' // set the css layer to inject to
  }
})

The icons will have the default size of 24px and the nuxt icon will be available:

<Icon name="nuxt" />

By default, this module will create a server endpoint /api/_nuxt_icon/:collection to serve the icons from your local server bundle (you can override the default path by setting icon.localApiEndpoint to your desired path). When requesting an icon that does not exist in the local bundle, it will fallback to requesting the official Iconify API. You can disable the fallback by setting icon.fallbackToApi to false, or set up your own Iconify API and update icon.iconifyApiEndpoint to your own API endpoint.

Customizing Icons with the customize Option

The customize option allows you to modify various aspects of the SVG icons used in your project. With this option, you can:

Change Stroke Width
Change Colors
Change Animation Duration
Change Opacity
Add Extra Shapes

You have full control over SVG content with these customization options.

In a Component You can define a customize function within a component to apply various modifications to your icons.

<script setup lang="ts">
// Define the customize function to modify SVG content
const customize = (content: string, name: string, prefix: string, provider: string) => {
  if (prefix !== 'tabler') return content // Ignore Prefix

  return content
    .replace(/stroke-width="[^"]*"/g, `stroke-width="2"`) // Change stroke width to 2
    .replace(/stroke="[^"]*"/g, `stroke="#FF5733"`) // Change stroke color to red
    .replace(/fill="[^"]*"/g, `fill="#FF5733"`) // Change fill color to red
    .replace(/animation-duration="[^"]*"/g, `animation-duration="1s"`) // Change animation durat

Icon

Install / Use

README