Add 100,000+ ready to use icons to your Nuxt application, based on Iconify.
<Icon />
components, so they will work in other components, like PrimeVueAdd nuxt-icon-tw
dependency to your project (it does require Tailwind of course):
npx nuxi@latest module add icon-tw
npx nuxi@latest module add tailwindcss
Add it to the modules
array in your nuxt.config.ts
:
import { defineNuxtConfig } from 'nuxt'
export default defineNuxtConfig({
modules: ['nuxt-icon-tw', '@nuxtjs/tailwindcss'],
})
Be sure it is before any other modules that might bring in @nuxt/icon so the Icon component from this package will be used first.
Install any Iconify JSON packages you want to use via Tailwind CSS:
npm install --save-dev @iconify-json/mdi
# Using yarn
yarn add --dev @iconify-jsom/mdi
These will be picked up automatically by the Tailwind CSS plugin.
<Icon />
will use Tailwind to load any icons starting with i-prefix
ie i-mdi-home
.
If you use i-other-icon
and it is a set not installed locally, the icon will fallback to Iconify API SVG loading
Any icons using a :
divider (ie i-mdi:home
or mdi:home
) will remain Iconify SVG since Tailwind does not allow : in classes.
This allows for NuxtIconTw to be a drop in replacement for NuxtIcon if you want to add Tailwind Icons to an existing project (incidentally, this is why I created this)
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
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" />
Other Components::
<Icon />
- Automatically set to Tailwind or Iconify SVG based on loaded collections<IconTw />
- Only creates icon by Tailwind - if the name specified is not loaded, it will be blank<IconSvg />
- Only creates icon by Iconify Svg - but custom files will not work hereYou 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
).
You can specify locations of custom icon JSON files to have them included in the Tailwind CSS:
import { createResolver } from '@nuxt/kit'
const { resolve } = createResolver(import.meta.url)
export default defineNuxtConfig({
icon: {
customCollections: resolve('./custom.json'),
},
modules: ['nuxt-icon-tw', '@nuxtjs/tailwindcss'],
})
Note you can also get these to show up in VS Code Iconify
{
// set from root of the project
"iconify.customCollectionJsonPaths": ["./playground/custom.json"]
}
<Icon name="🚀" />
<Icon name="NuxtIcon" />
Note that NuxtIcon
needs to be inside components/global/
folder (see example).
You can specify what prefix you want to use on Tailwind Icons classes. This defaults to i
for backwards compatibility with other Tailwind Icons plugins.
However, it can be set empty (''
) to not require a prefix at all.
Specify the Iconify sets you wish to include
string[]
:
export default defineNuxtConfig({
icon: {
collections: ['mdi', 'ph'],
},
modules: ['nuxt-icon-tw', '@nuxtjs/tailwindcss'],
})
[]
: turn off automated resolution altogether
'all'
: specifically opt in to loading the full Iconify JSON; warning: can be slow
IconCollection
: entirely override the automation
export default defineNuxtConfig({
icon: {
collections: {
foo: {
icons: {
'arrow-left': {
body: '<path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M10.5 19.5L3 12m0 0l7.5-7.5M3 12h18"/>',
width: 20,
height: 20,
},
},
},
},
},
modules: ['nuxt-icon-tw', '@nuxtjs/tailwindcss'],
})
If you should want to only allow Tailwind Icons and no Iconify API icons at all, set this to true.
export default defineNuxtConfig({
icon: {
forceTailwind: true,
},
modules: ['nuxt-icon-tw', '@nuxtjs/tailwindcss'],
})
To update the default size (1em
) of the <Icon />
, create an app.config.ts
with the iconTw.size
property.
The app.config.ts
will override any size setting in nuxt.config.ts
Update the default class (.icon
) of the <Icon />
with the iconTw.class
property, for a headless Icon, simply set iconTw.class: ''
.
You can also define aliases to make swapping out icons easier by leveraging the iconTw.aliases
property.
// app.config.ts
export default defineAppConfig({
iconTw: {
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 iconTw.iconifyApiOptions.url
property to your own Iconify API.
You can also set iconTw.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({
iconTw: {
// ...
iconifyApiOptions: {
url: 'https://<your-api-url>',
publicApiFallback: true, // default: false
},
},
})
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>
pnpm install
(install pnpm
with corepack enable
, learn more)npm run dev:prepare
to generate type stubs.npm run dev
to start playground in development mode.