Usage
Nuxt UI automatically registers the @nuxt/icon module for you, so there's no additional setup required.
Icon component
You can use the Icon component with a name prop to display an icon:
<template>
<UIcon name="i-lucide-lightbulb" class="size-5" />
</template>
search-icons MCP tool.Component props
Some components also have an icon prop to display an icon, like the Button for example:
<template>
<UButton icon="i-lucide-sun" variant="subtle">Button</UButton>
</template>
Collections
Iconify dataset
It's highly recommended to install the icon data locally with:
pnpm i @iconify-json/{collection_name}
yarn add @iconify-json/{collection_name}
npm install @iconify-json/{collection_name}
For example, to use the i-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.
Installing the collection also lets Nuxt UI embed the icons it uses into the client bundle at build time, so they're available on first render instead of being loaded on demand at runtime. This happens automatically for Nuxt UI's own icons, from the lucide collection by default. To bundle other icons, such as ones you override or use elsewhere in your app, add them to @nuxt/icon's clientBundle.icons option in your nuxt.config.ts:
export default defineNuxtConfig({
modules: ['@nuxt/ui'],
css: ['~/assets/css/main.css'],
icon: {
clientBundle: {
icons: ['lucide:heart', 'simple-icons:github']
}
}
})
Or enable clientBundle.scan to bundle every icon used across your app by scanning your source, so you don't have to list them one by one:
export default defineNuxtConfig({
modules: ['@nuxt/ui'],
css: ['~/assets/css/main.css'],
icon: {
clientBundle: {
scan: true
}
}
})
Custom local collections
You can use local SVG files to create a custom Iconify collection.
For example, place your icons' SVG files under a folder of your choice, for example, ./app/assets/icons:
assets/icons
├── add.svg
└── remove.svg
In your nuxt.config.ts, add an item in icon.customCollections:
export default defineNuxtConfig({
modules: ['@nuxt/ui'],
css: ['~/assets/css/main.css'],
icon: {
customCollections: [{
prefix: 'custom',
dir: './app/assets/icons'
}]
}
})
Then you can use the icons like this:
<template>
<UIcon name="i-custom-add" />
</template>
Theme
You can change the default icons used by components in your app.config.ts:
export default defineAppConfig({
ui: {
icons: {
arrowDown: 'i-lucide-arrow-down',
arrowLeft: 'i-lucide-arrow-left',
arrowRight: 'i-lucide-arrow-right',
arrowUp: 'i-lucide-arrow-up',
caution: 'i-lucide-circle-alert',
check: 'i-lucide-check',
chevronDoubleLeft: 'i-lucide-chevrons-left',
chevronDoubleRight: 'i-lucide-chevrons-right',
chevronDown: 'i-lucide-chevron-down',
chevronLeft: 'i-lucide-chevron-left',
chevronRight: 'i-lucide-chevron-right',
chevronUp: 'i-lucide-chevron-up',
close: 'i-lucide-x',
copy: 'i-lucide-copy',
copyCheck: 'i-lucide-copy-check',
dark: 'i-lucide-moon',
drag: 'i-lucide-grip-vertical',
ellipsis: 'i-lucide-ellipsis',
error: 'i-lucide-circle-x',
external: 'i-lucide-arrow-up-right',
eye: 'i-lucide-eye',
eyeOff: 'i-lucide-eye-off',
file: 'i-lucide-file',
folder: 'i-lucide-folder',
folderOpen: 'i-lucide-folder-open',
hash: 'i-lucide-hash',
info: 'i-lucide-info',
light: 'i-lucide-sun',
loading: 'i-lucide-loader-circle',
menu: 'i-lucide-menu',
minus: 'i-lucide-minus',
panelClose: 'i-lucide-panel-left-close',
panelOpen: 'i-lucide-panel-left-open',
plus: 'i-lucide-plus',
reload: 'i-lucide-rotate-ccw',
search: 'i-lucide-search',
stop: 'i-lucide-square',
star: 'i-lucide-star',
success: 'i-lucide-circle-check',
system: 'i-lucide-monitor',
tip: 'i-lucide-lightbulb',
upload: 'i-lucide-upload',
warning: 'i-lucide-triangle-alert'
}
}
})
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'
export default defineConfig({
plugins: [
vue(),
ui({
ui: {
icons: {
arrowDown: 'i-lucide-arrow-down',
arrowLeft: 'i-lucide-arrow-left',
arrowRight: 'i-lucide-arrow-right',
arrowUp: 'i-lucide-arrow-up',
caution: 'i-lucide-circle-alert',
check: 'i-lucide-check',
chevronDoubleLeft: 'i-lucide-chevrons-left',
chevronDoubleRight: 'i-lucide-chevrons-right',
chevronDown: 'i-lucide-chevron-down',
chevronLeft: 'i-lucide-chevron-left',
chevronRight: 'i-lucide-chevron-right',
chevronUp: 'i-lucide-chevron-up',
close: 'i-lucide-x',
copy: 'i-lucide-copy',
copyCheck: 'i-lucide-copy-check',
dark: 'i-lucide-moon',
drag: 'i-lucide-grip-vertical',
ellipsis: 'i-lucide-ellipsis',
error: 'i-lucide-circle-x',
external: 'i-lucide-arrow-up-right',
eye: 'i-lucide-eye',
eyeOff: 'i-lucide-eye-off',
file: 'i-lucide-file',
folder: 'i-lucide-folder',
folderOpen: 'i-lucide-folder-open',
hash: 'i-lucide-hash',
info: 'i-lucide-info',
light: 'i-lucide-sun',
loading: 'i-lucide-loader-circle',
menu: 'i-lucide-menu',
minus: 'i-lucide-minus',
panelClose: 'i-lucide-panel-left-close',
panelOpen: 'i-lucide-panel-left-open',
plus: 'i-lucide-plus',
reload: 'i-lucide-rotate-ccw',
search: 'i-lucide-search',
stop: 'i-lucide-square',
star: 'i-lucide-star',
success: 'i-lucide-circle-check',
system: 'i-lucide-monitor',
tip: 'i-lucide-lightbulb',
upload: 'i-lucide-upload',
warning: 'i-lucide-triangle-alert'
}
}
})
]
})
app.config.ts are loaded on demand at runtime rather than embedded in the client bundle. To bundle them too, add them in {collection}:{name} form (for example lucide:rocket) to @nuxt/icon's clientBundle.icons in your nuxt.config.ts.