Nuxt Icon

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

Features ✨

Nuxt 3 ready
Support 200,000 open source vector icons via Iconify
Emoji Support
Custom SVG support (via Vue component)

Setup ⛓️

Add nuxt-icon dependency to your project:

npm install --save-dev nuxt-icon

# Using yarn
yarn add --dev nuxt-icon

Add it to the modules array in your nuxt.config.ts:

import { defineNuxtConfig } from 'nuxt'

export default defineNuxtConfig({
  modules: ['nuxt-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

Usage 👌

Props:

name (required): icon name, emoji or global component name
size: icon size (default: 1em)

Attributes:

When using an icon from Iconify, an <svg> will be created, you can give all the attributes of the native element.

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

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

Emoji

<Icon name="🚀" />

Vue component

<Icon name="NuxtIcon" />

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

Configuration ⚙️

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

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

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

// app.config.ts
export default defineAppConfig({
  nuxtIcon: {
    size: '24px', // default <Icon> size applied
    class: 'icon', // default <Icon> class applied
    aliases: {
      'nuxt': 'logos:nuxt-icon',
    }
  }
})

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

<Icon name="nuxt" />

By default, this module will fetch the Icons from the official Iconify API. You can change this behavior by setting the nuxtIcon.iconifyApiOptions.url property to your own Iconify API.

You can also set nuxtIcon.iconifyApiOptions.publicApiFallback to true to use the public API as a fallback (only for the <Icon> component, not for the <IconCSS> component`)

// app.config.ts
export default defineAppConfig({
  nuxtIcon: {
    // ...
    iconifyApiOptions: {
      url: 'https://<your-api-url>',
      publicApiFallback: true // default: false
    }
  }
})

Render Function

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:

import { Icon } from '#components'

See an example of a <MyIcon> component:

<script setup>
import { Icon } from '#components'

const MyIcon = h(Icon, { name: 'uil:twitter' })
</script>

<template>
  <p><MyIcon /></p>
</template>

This is currently experimental and may change in the future, this is a way to use CSS icons instead of SVG icons to reduce the DOM size and improve performance. It is leveraging the Mask combined with background color set to currentColor, useful to render monotone icons that use currentColor as icon color. Learn more on https://docs.iconify.design/icon-components/css.html

<template>
  <IconCSS name="uil:twitter" />
</template>

You can use aliases in <IconCSS> as well.

Note that CSS Masks have limited support, see https://caniuse.com/css-masks for more information.

Also, the icons won't be loaded on initial load and an HTTP request will be made to Iconify CDN to load them.

Contributing 🙏

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

Credits 💌

@benjamincanac for the initial version
@cyberalien for making Iconify

License 📎

MIT License