Using UnoCSS Icon Preset to Load Custom SVG Icons Without Extra Resources

Most front‑end developers have used the iconfont solution, which treats icons as fonts and requires uploading SVGs to a service, generating CSS/JS/JSON files, and adding extra font resources that can cause conflicts. While convenient, this approach has drawbacks such as resource overhead and limited flexibility.

UnoCSS offers a more streamlined alternative. It provides an Icons preset that works like Tailwind's atomic CSS but can be used independently. By installing the preset and a desired icon collection (e.g., the Carbon icons from @iconify-json/carbon), you can reference icons directly in markup. pnpm i -D @iconify-json/carbon After adding the preset to your UnoCSS configuration, an icon can be rendered with a simple class name: <div class="i-carbon-sun text-3xl c-yellow" /> The utility classes text-3xl and c-yellow control the icon size and color, respectively.

UnoCSS also supports loading your own SVG files via FileSystemIconLoader. Install the helper library: pnpm i -D @iconify/utils Configure UnoCSS to read all .svg files in a folder (e.g., ./src/assets/svg) and expose them under a custom prefix:

import { defineConfig, presetIcons } from 'unocss';
import { FileSystemIconLoader } from '@iconify/utils/lib/loader/node-loaders';

export default defineConfig({
  presets: [
    presetIcons({
      collections: {
        my: FileSystemIconLoader('./src/assets/svg')
      }
    })
  ]
});

With a file sun.svg placed in that folder, you can use it as:

<div i-my-sun />

<div i-my-sun text-xl c-yellow />

This makes adding new icons as easy as dropping an SVG into the project.

For large projects, organize icons into separate sub‑folders and assign distinct prefixes to avoid naming collisions:

export default defineConfig({
  presets: [
    presetIcons({
      collections: {
        user: FileSystemIconLoader('./src/assets/svg/user'),
        dashboard: FileSystemIconLoader('./src/assets/svg/dashboard'),
        login: FileSystemIconLoader('./src/assets/svg/login')
        // ...
      }
    })
  ]
});

When SVGs use 1em for width and height, their size can be controlled via font‑size utilities. You can enforce this with a simple regex transformation during loading:

FileSystemIconLoader(
  './src/assets/svg',
  svg => svg
    .replace(/(<svg.*?width=)"(.*?)"/, '$1"1em"')
    .replace(/(<svg.*?height=)"(.*?)"/, '$1"1em"')
);

UnoCSS renders icons either as background‑img or as a mask‑image. Icons that contain currentColor are rendered with the mask method by default, allowing their color to follow the surrounding text color. You can explicitly choose the rendering mode:

<div class="i-my-sun?mask" c-yellow />

<div class="i-my-moon?bg" />

By ensuring SVGs use currentColor for fill or stroke, you enable seamless color changes via UnoCSS utilities.

Overall, UnoCSS's icon preset provides a lightweight, flexible, and resource‑efficient way to manage both third‑party and custom SVG icons in front‑end projects.