48.1K
icon

icon

Icon module for Nuxt with 100,000+ ready to use icons from Iconify.

112.8K downloads
654 stars
AtinuxAtinux

nuxt-icon

Nuxt Icon

npm versionnpm downloadsLicenseNuxtVolta board

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

Features ✨

  • Nuxt 3 ready
  • Support 100,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 yarnyarn 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.tsexport 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.tsexport 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>

CSS Icons

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 🙏

  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 💌

License 📎

MIT License