Integrating Unocss Icon Solution into a Vite Vue Project

The article begins with a brief overview of traditional icon methods such as CSS sprites, font‑based icons (e.g., Font Awesome, Alibaba Iconfont), pure‑CSS icons, and SVG‑based icons, highlighting their advantages and limitations.

Unocss Icon Scheme

Unocss icons are implemented as pure CSS icons that leverage SVG and the Iconify ecosystem. The author references antfu’s article on pure CSS icons for deeper insight and explains that Unocss icons inherit the benefits of Iconify while being usable via simple CSS classes.

How to Use

A new Vite Vue project is created (using pnpm create vite unocss-icon ), and the necessary dependencies ( unocss and @iconify/json ) are installed.

The vite.config.js file is updated to include the Unocss plugin:

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import Unocss from 'unocss/vite'

export default defineConfig({
  plugins: [
    vue(),
    Unocss()
  ],
})

A uno.config.js file is added to configure the presetIcons preset with a custom prefix (e.g., i- ) and default display properties.

import { defineConfig, presetIcons, presetUno } from 'unocss'

export default defineConfig({
  presets: [
    presetUno(),
    presetIcons({
      warn: true,
      prefix: ['i-'],
      extraProperties: {
        display: 'inline-block',
      },
    })
  ]
})

The entry file src/main.js imports uno.css (and removes the default style.css ) and mounts the Vue app.

import { createApp } from 'vue'
import 'uno.css'
import App from './App.vue'

createApp(App).mount('#app')

The App.vue template is replaced with a simple example that displays two icons using the generated classes:

<template>
  <div class="flex gap-3 text-5xl text-red-300">
    <i class="i-vscode-icons:file-type-light-pnpm" />
    <i class="i-vscode-icons:file-type-light-pnpm?mask" />
  </div>
</template>

Running the project shows the icons, confirming the setup.

Finding and Using Icons

All icons available in the Iconify ecosystem can be browsed at Icônes . After selecting an icon, copy its class string (e.g., i-[icon‑set]:[icon‑name] ) and add it to the element’s class attribute. The i tag is not mandatory; any element can host the class, and the prefix i- can be customized in uno.config.js .

Summary

Advantages of Unocss Icons

Seamless compatibility with the Iconify ecosystem, offering over a hundred icon sets and hundreds of thousands of icons.

Scalable without loss of quality.

Color and size automatically follow surrounding text styles.

Support for multi‑color icons similar to emojis.

Simple integration via a single CSS class per icon.

Easy updates by upgrading the @iconify/json dependency.

On‑demand loading reduces bundle size.

Limitations

The main drawback is the inability to dynamically load icons at runtime, a limitation shared by most icon solutions except Iconify, which can load icons on demand but may cause network latency and flashing in restricted environments. This can be mitigated by adding likely icons to the safelist , though it increases the final CSS size.

Further articles will cover custom icon sets and advanced usage; readers are encouraged to explore the Unocss documentation and the author’s open‑source project vue-naive-admin for practical examples.