Nuxt UI integrates with Nuxt Icon to access over 200,000+ icons from Iconify.

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>
You can use any name from the https://icones.js.org collection.

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}

For example, to use the i-uil-github icon, install it's 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.

Read more about this in the @nuxt/icon documentation.

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, ./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'
  ],
  icon: {
    customCollections: [{
      prefix: 'custom',
      dir: './assets/icons'
    }]
  }
})

Then you can use the icons like this:

<template>
  <UIcon name="i-custom-add" />
</template>
Read more about this in the @nuxt/icon documentation.

Theme

You can change the default icons used by components in your app.config.ts:

app.config.ts
export default defineAppConfig({
  ui: {
    icons: {
      arrowLeft: 'i-lucide-arrow-left',
      arrowRight: 'i-lucide-arrow-right',
      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',
      ellipsis: 'i-lucide-ellipsis',
      external: 'i-lucide-arrow-up-right',
      loading: 'i-lucide-refresh-cw',
      minus: 'i-lucide-minus',
      plus: 'i-lucide-plus',
      search: 'i-lucide-search'
    }
  }
})
app.config.ts
export default defineAppConfig({
  ui: {
    icons: {
      caution: 'i-lucide-circle-alert',
      copy: 'i-lucide-copy',
      copyCheck: 'i-lucide-copy-check',
      dark: 'i-lucide-moon',
      file: 'i-lucide-file-text',
      folder: 'i-lucide-folder',
      folderOpen: 'i-lucide-folder-open',
      external: 'i-lucide-arrow-up-right',
      hash: 'i-lucide-hash',
      light: 'i-lucide-sun',
      menu: 'i-lucide-menu',
      note: 'i-lucide-info',
      system: 'i-lucide-monitor',
      tip: 'i-lucide-lightbulb',
      warning: 'i-lucide-triangle-alert',
      arrowLeft: 'i-lucide-arrow-left',
      arrowRight: 'i-lucide-arrow-right',
      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',
      ellipsis: 'i-lucide-ellipsis',
      loading: 'i-lucide-refresh-cw',
      minus: 'i-lucide-minus',
      plus: 'i-lucide-plus',
      search: 'i-lucide-search'
    }
  }
})
Nuxt UI Pro v3 does not support Vue yet.
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      ui: {
        icons: {
          arrowLeft: 'i-lucide-arrow-left',
          arrowRight: 'i-lucide-arrow-right',
          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',
          ellipsis: 'i-lucide-ellipsis',
          external: 'i-lucide-arrow-up-right',
          loading: 'i-lucide-refresh-cw',
          minus: 'i-lucide-minus',
          plus: 'i-lucide-plus',
          search: 'i-lucide-search'
        }
      }
    })
  ]
})