Nuxt Icon

Nuxt Icon allows you to use over 200,000 ready-to-use vector icons from the Iconify dataset in your Nuxt application.

Key features include:

• Nuxt 3 Ready: Built specifically for the Nuxt 3 ecosystem.
• SSR Friendly: Works seamlessly with Server-Side Rendering.
• Iconify Support: Access a massive library of open-source vector icons.
• Flexible Rendering: Supports both CSS mode and SVG mode.
• Custom SVG Support: Use your own custom SVGs via Vue components or local SVG files.

If the name prop matches a globally registered Nuxt component, the <Icon /> component will render that component instead of an icon. Note that mode is ignored in this case. For this to work, the component must be located in the components/global/ directory.

<Icon name="MyComponent" />

You can add the Nuxt Icon module to your project using the Nuxt CLI or by installing it manually.

Using Nuxt CLI (Recommended)

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

npx nuxi module add icon

Manual Installation

If you prefer manual installation, install the package via npm:

npm i @nuxt/icon

Then, add the module to your nuxt.config.ts file:

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

IMPORTANT

If you are migrating from the legacy nuxt-icon module, ensure you remove it from your modules list to avoid conflicts.

To ensure icons are served locally (faster and more reliable for SSR and client-side), install the specific Iconify JSON collection for the icons you need using npm. For example, to use uil:github, install @iconify-json/uil.

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

If you are using Vue with Vite (without Nuxt), you can use the @nuxt/icon/vite plugin to pre-bundle icons into your client build. This allows for offline rendering and SSR support without a Nuxt server.

1. Install the plugin and your icon collections.
2. Add NuxtIconBundle to your vite.config.ts.
3. Register the bundle in your entry file (e.g., main.ts) using the virtual module virtual:nuxt-icon-bundle/register.
4. Add @nuxt/icon/client to your tsconfig.json types.

// vite.config.ts
import { defineConfig } from 'vite'
import { NuxtIconBundle } from '@nuxt/icon/vite'

export default defineConfig({
  plugins: [
    NuxtIconBundle({
      icons: ['uil:github', 'heroicons:home'],
      scan: true,
    }),
  ],
})

// main.ts
import 'virtual:nuxt-icon-bundle/register'

To avoid network requests for frequently used icons, you can include them in the client bundle.

• icons: An array of specific icon names to pre-bundle.
• scan: When true, the module scans your source files for literal icon names and includes them automatically.
• includeCustomCollections: Includes all your customCollections in the client bundle.
• sizeLimitKb: A guard that fails the build if the client bundle exceeds this size.

Warning: Static scanning only detects literal icon names. Avoid constructing icon names dynamically (e.g., :name="icon:${type}") if you rely on scanning.

export default defineNuxtConfig({
  modules: [
    '@nuxt/icon',
  ],
  icon: {
    clientBundle: {
      icons: ['uil:github', 'heroicons:home'],
      scan: true,
    },
  },
})

Use app.config.ts to set runtime defaults for all <Icon /> components. This includes size, class, mode, aliases, and customize functions. Note that app.config.ts is for runtime configuration, whereas nuxt.config.ts is for build-time/module configuration.

// app.config.ts
export default defineAppConfig({
  icon: {
    size: '24px',
    class: 'icon',
    mode: 'css',
    aliases: {
      'nuxt': 'logos:nuxt-icon',
    },
    cssLayer: 'base'
  }
})

When using TailwindCSS v4 with the css rendering mode, you must configure the cssLayer in your app.config.ts to ensure correct styling.

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

Nuxt Icon supports several ways to resolve and load icon collections:

• Iconify JSON Packages: It automatically detects installed @iconify/json or @iconify-json/* packages.
• Custom Collections: Loading local SVG files via a directory path.
• Remote Collections: Loading collections from remote sources.

If you are using @iconify/json, all collections are discovered by default, but for better performance, it is recommended to explicitly list the collections you use in the icon.serverBundle.collections option.

The UnoCSS integration allows Nuxt Icon to automatically detect and skip fetching icons that are already being handled by UnoCSS via CSS classes. It works by extracting known CSS classes from the UnoCSS generator and adding them to serverKnownCssClasses.

How it works

• In Production/Build: A Vite plugin extracts the icon classes used in the client build and adds them to the serverKnownCssClasses option for the server build.
• In Development: The integration proxies the Nitro runtime configuration to dynamically include the latest icon classes detected by UnoCSS via a getter.

Configuration

The integration respects the cssSelectorPrefix option to identify which classes belong to icons. If not specified, it defaults to i-.