!nuxt-icon

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]

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

- ✨  Release Notes
- 🏀  Online playground

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:

``bash
npx nuxi module add icon
`

That's it, you can now use the in your components!

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

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 or will be created based on the rendering mode, you can give all the attributes of the native element.

`html

`

TailwindCSS v4:

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

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

$3

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

`html

`

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

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

`bash
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:
>
> `ts
> export default defineNuxtConfig({
> modules: ['@nuxt/icon'],
> icon: {
> serverBundle: {
> collections: ['uil', 'mdi'] //
`

In the App Configuration File:

Alternatively, you can apply these customizations globally in the app.config.ts file.
`ts
// app.config.ts
export default defineAppConfig({
icon: {
customize: (content: string, name: string, prefix: string, provider: string) => {
// ...
},
}
})
`
With this configuration, all icons throughout your application will have these customizations applied consistently.

$3

Since @nuxt/icon v1.0, we have introduced the server bundle concept to serve the icons from Nuxt server endpoints. This keeps the client bundle lean and able to load icons on-demand, while having all the dynamic features to use icons that might not be known at build time.

#### Server Bundle Mode: local

This mode will bundle the icon collections you have installed locally (like @iconify-json/*), into your server bundle as dynamic chunks. The collection data will be loaded on-demand, only when your client request icons from that collection.

#### Server Bundle Mode: remote

Introduced in @nuxt/icon v1.2, you can now use the remote server bundle to serve the icons from a remote CDN.

`ts
export default defineNuxtConfig({
modules: [
'@nuxt/icon'
],
icon: {
serverBundle: 'remote',
},
})
`

Or you can specify the remote provider:

`ts
export default defineNuxtConfig({
modules: [
'@nuxt/icon'
],
icon: {
serverBundle: {
remote: 'jsdelivr', // 'unpkg' or 'github-raw', or a custom function
}
},
})
`

Which will make server requests to https://cdn.jsdelivr.net/npm/@iconify-json/ph/icons.json to fetch the icons at runtime, instead of bundling them with your server.

Under the hood, instead of bundling () => import('@iconify-json/ph/icons.json') to your server bundle, it will now use something like () => fetch('https://cdn.jsdelivr.net/npm/@iconify-json/ph/icons.json').then(res => res.json()), where the collections are not inlined.

This would be useful when server bundle size is a concern, like in serverless or worker environments.

#### Server Bundle Mode: auto

This is the default option, where the module will pick between local and remote based your deployment environment. local will be preffered unless you are deploying to a serverless or worker environment, like Vercel Edge or Cloudflare Workers.

#### Externalize Icons JSON

By default, Nitro will bundle the icon collections you have installed locally (like @iconify-json/*), into your server bundle as dynamic chunks. When you have a large number of icons, this might make your bundling process slow and memory-intensive. You can change to externalize the icons JSON files by setting icon.serverBundle.externalizeIconsJson to true.

`ts
export default defineNuxtConfig({
modules: [
'@nuxt/icon'
],
icon: {
serverBundle: {
externalizeIconsJson: true,
}
},
})
`

Note that this will require your production Node.js server to be able to import JSON files (Note that as in Node.js v22, JSON modules are still an experimental feature). In the final build, it will contain statements like () => import('@iconify-json/ph/icons.json', { with: { type: 'json' } }).

Also note that in some serverless environments, like Cloudflare Workers, where they don't have dynamic imports, they will always be inlined regardless of this option.

This option will be ignored when icon.serverBundle.remote is enabled.

#### Completely Disable Server Bundle

If you want to disable the server bundle completely, you can set icon.serverBundle to false and provider to iconify

`ts
export default defineNuxtConfig({
modules: [
'@nuxt/icon'
],
icon: {
provider: 'iconify',
serverBundle: false,
},
})
`

This will make requests to Iconify API every time the client requests an icon. We do not recommend doing so unless the other options are not feasible.

$3

For icons that you know you are going to use frequently, you can bundle them with your client bundle to avoid network requests.

`ts
export default defineNuxtConfig({
modules: [
'@nuxt/icon'
],
icon: {
clientBundle: {
// list of icons to include in the client bundle
icons: [
'uil:github',
'logos:vitejs'
],

// scan all components in the project and include icons
scan: true,

// include all custom collections in the client bundle
includeCustomCollections: true,

// guard for uncompressed bundle size, will fail the build if exceeds
sizeLimitKb: 256,
},
},
})
`

includeCustomCollections will include all the custom collections you have defined in icon.customCollections in the client bundle. It's disabled by default but will automatically enable when ssr: false is set.

#### Scan Components

When scan is enabled, the module will scan all the components in your project and include the icons used in the client bundle. This would significantly reduce the number of network requests needed for statically known icons, but might also increase the client bundle size depending on the number of icons used in your project.

You can also fine-tune tine scanning targets like:

`ts
export default defineNuxtConfig({
modules: [
'@nuxt/icon'
],
icon: {
clientBundle: {
scan: {
// note that when you specify those values, the default behavior will be overridden
globInclude: ['components/*/.vue', / ... /],
globExclude: ['node_modules', 'dist', / ... /],
},
},
},
})
`

> [!TIP]
> Scanning is relying on static analysis, which means only literal usages will be detected. Avoid constructing the icon name dynamically whenever possible.
>
> `vue
>
> `

$3

You can use the Icon component in a render function (useful if you create a functional component), for this you can import it from #components:

`ts
import { Icon } from '#components'
`

See an example of a component:

`vue



`

$3

In in-browser component testing environments (such as Vitest Browser Mode or Cypress Component Testing), the internal Nuxt server routes used to fetch icons on demand are not available. As a result, icons may fail to render during tests.

To ensure icons render correctly in component tests, configure @nuxt/icon to use the client bundle when running in test mode.

> Note
> Projects using @nuxt/ui must do this to see any UI icons during component testing.

#### Requirements

* Install the icon collections you use locally (for example, @iconify-json/lucide).
* Icons will not be fetched remotely when using the client bundle.

#### Test-only Configuration

Conditionally switch to the client bundle in your Nuxt config when NODE_ENV === 'test':

`ts
export default defineNuxtConfig({
modules: [
'@nuxt/icon',
],

icon: process.env.NODE_ENV !== 'test'
? {
// Production or development icon configuration
}
: {
// Disable all network icon fetching in component tests
provider: 'none',

clientBundle: {
// Explicitly include dynamically constructed icons
icons: ['lucide:check'],

// Scan your app and Nuxt UI runtime for static icon usage
scan: {
globInclude: [
'{app,shared}/**',
'node_modules/@nuxt/ui/dist/**',
],
globExclude: ['node_modules'],
},
},
},
})
`

> Tips
>
> * Dynamically generated icon names may not be detected by static scanning—add them explicitly to icons.
> * For large apps, consider moving test-only configuration into vitest.config.ts or cypress.config.ts for clarity.

Contributing 🙏

1. Clone this repository
2. Install dependencies using pnpm install (install pnpm with corepack enable, learn more)
3. Run npm run dev:prepare to generate type stubs.
4. Use npm run dev` to start playground in development mode.

Credits 💌

- @benjamincanac for the initial version
- @cyberalien for making Iconify

License 📎

MIT License

[npm-version-src]: https://img.shields.io/npm/v/@nuxt/icon/latest.svg?style=flat&colorA=18181B&colorB=28CF8D
[npm-version-href]: https://npmjs.com/package/@nuxt/icon

[npm-downloads-src]: https://img.shields.io/npm/dm/@nuxt/icon.svg?style=flat&colorA=18181B&colorB=28CF8D
[npm-downloads-href]: https://npmjs.com/package/@nuxt/icon

[license-src]: https://img.shields.io/github/license/nuxt-modules/icon.svg?style=flat&colorA=18181B&colorB=28CF8D
[license-href]: https://github.com/nuxt-modules/icon/blob/main/LICENSE

[nuxt-src]: https://img.shields.io/badge/Nuxt-18181B?logo=nuxt.js
[nuxt-href]: https://nuxt.com