icon
Icon module for Nuxt with 100,000+ ready to use icons from Iconify.
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 namesize
: 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>
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 ๐
- Clone this repository
- Install dependencies using
pnpm install
(installpnpm
withcorepack 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