Skip to main content

​
Overview

Nuxt UI includes built-in support for icons through the @nuxt/icon module, which is automatically installed and configured when you use Nuxt UI.

​
Icon Module

The @nuxt/icon module is automatically registered by Nuxt UI with optimized settings: 
// Automatically configured by Nuxt UI
{
  icon: {
    cssLayer: 'base'
  }
}

​
Using Icons

​
Icon Component

Use the UIcon component to display icons throughout your application: 
<template>
  <UIcon name="i-heroicons-home" />
</template>

​
Icon Collections

Nuxt Icon supports multiple icon collections. You can use icons from:
  • Heroicons - i-heroicons-{name}
  • Material Design Icons - i-mdi-{name}
  • Phosphor - i-ph-{name}
  • Tabler - i-tabler-{name}
  • And 100,000+ other icons
<UIcon name="i-heroicons-star" />

​
Icons in Components

Many Nuxt UI components accept icon props to enhance their appearance:

​
Buttons

<template>
  <UButton
    icon="i-heroicons-check"
    trailing-icon="i-heroicons-arrow-right"
  >
    Continue
  </UButton>
</template>

​
Input Fields

<template>
  <UInput
    icon="i-heroicons-magnifying-glass"
    placeholder="Search..."
  />
</template>

​
Alerts

<template>
  <UAlert
    icon="i-heroicons-information-circle"
    title="Information"
    description="This is an informational message."
  />
</template>

​
AppConfig Icons

Nuxt UI uses icons defined in your app.config.ts for various UI elements. You can customize these default icons:
app.config.ts
export default defineAppConfig({
  ui: {
    icons: {
      dark: 'i-heroicons-moon',
      light: 'i-heroicons-sun',
      search: 'i-heroicons-magnifying-glass',
      close: 'i-heroicons-x-mark',
      check: 'i-heroicons-check'
    }
  }
})
These icons are used throughout Nuxt UI components:
  • dark / light - Color mode toggle buttons
  • search - Search inputs and command palettes
  • close - Modal, drawer, and alert close buttons
  • check - Checkbox and selection indicators

​
Custom SVG Icons

You can also use custom SVG icons by adding them to your public/icons directory:
1

Create icons directory

Create a public/icons directory in your project root.
2

Add SVG files

Add your custom SVG files to the directory:
public/icons/custom-logo.svg
3

Use the icon

Reference your custom icon using the file path:
<UIcon name="i-custom-logo" />

​
Icon Sizing

Control icon size using Tailwind CSS classes: 
<template>
  <UIcon name="i-heroicons-star" class="w-4 h-4" />
  <UIcon name="i-heroicons-star" class="w-6 h-6" />
  <UIcon name="i-heroicons-star" class="w-8 h-8" />
</template>

​
Icon Colors

Icons inherit the text color from their parent element: 
<template>
  <UIcon name="i-heroicons-heart" class="text-error" />
  <UIcon name="i-heroicons-check" class="text-success" />
  <UIcon name="i-heroicons-star" class="text-primary" />
</template>
Icons in Nuxt UI use semantic color tokens like text-primary, text-error, etc. See the Theme documentation for more information.

​
Server-Side Rendering

Icons are fully compatible with SSR. The @nuxt/icon module handles server-side rendering automatically, ensuring icons are displayed correctly on both server and client.

​
Performance

The icon module only bundles icons that are actually used in your application, keeping your bundle size minimal.
Avoid using dynamic icon names with string interpolation as this prevents proper tree-shaking. Use computed properties or static icon names instead.

​
Learn More

Build docs developers (and LLMs) love

Get started for freeTalk to us