kiconify

kiconify

An offline Iconify icon solution for Vue 3.

kiconify lets you use Iconify's prerendered Vue icon collections locally, without relying on the Iconify CDN at runtime. It also includes a Vite build plugin that detects statically-used KIconify icons and keeps only the required icons from large prerendered collections in the production bundle.

Features

• Offline icon rendering with Iconify prerendered Vue collections
• Simple icon API:

<KIconify name="solar:home-bold" />

• Supports icon collections such as Solar, Phosphor, and other @iconify-prerendered/vue-* packages
• Supports icon variants through the normal Iconify collection naming
• Built-in svg-spinners package from @iconify-prerendered/vue-svg-spinners
• Development icon search page for finding icons and variants
• Vite plugin for reducing production bundle size by detecting statically-used icons
• Vue 3 support

Installation

Install kiconify and the Iconify prerendered collections you want to use.

npm install kiconify
npm install @iconify-prerendered/vue-solar
npm install @iconify-prerendered/vue-ph

You can install any other compatible @iconify-prerendered/vue-* collection in the same way.

Setup

1. Configure the Vite plugin

Add the kiconify Vite plugin to the consuming project's vite.config.ts:

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { kiconifyVitePlugin } from 'kiconify/vite'

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

The plugin is used during production builds to detect statically-declared KIconify usages and optimize prerendered collection imports.

2. Register icon collections

In main.ts, import the collections as namespaces and pass them to kiconify:

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

import KIconifyPlugin from 'kiconify'
import * as solarIcons from '@iconify-prerendered/vue-solar'
import * as phIcons from '@iconify-prerendered/vue-ph'

const app = createApp(App)

app.use(KIconifyPlugin, {
  defaultColor: 'currentColor',
  defaultSize: 24,
  packages: {
    solar: solarIcons,
    ph: phIcons
  }
})

app.mount('#app')

Usage

Use the package name and icon name in the package:icon-name format:

<KIconify name="solar:home-bold" />
<KIconify name="solar:user-bold" :size="32" />
<KIconify name="ph:house" color="tomato" />

Available props:

Production bundle optimization

Large Iconify collections can contain thousands of icons. Importing a whole collection as a namespace can otherwise make the production bundle much larger than necessary.

The kiconifyVitePlugin() scans the project's source files for static usages such as:

<KIconify name="solar:home-bold" />
<KIconify name="solar:home-outline" />
<KIconify name="ph:house" />

During vite build, it detects the used icons and rewrites the prerendered namespace imports so that the build can keep only the required icon components.

For example, a collection containing thousands of icons can be reduced to only the icons actually referenced statically by the application.

Important limitation in 2.0.0

The optimizer in 2.0.0 targets static name="package:icon-name" usages. Dynamic values such as the following are not statically detectable by the current optimizer:

<KIconify :name="iconName" />

Icon search page

KIconifySearchPage is included as a development helper for browsing registered collections, searching icon names, filtering by collection, and copying icon names.

Example:

<KIconifySearchPage />

It reads the registered icon collections and displays the available icons and their names.

Built-in spinner collection

kiconify includes the @iconify-prerendered/vue-svg-spinners collection internally and registers it under the svg-spinners package.

Example:

<KIconify name="svg-spinners:..." />

The exact available spinner names depend on the installed prerendered spinner package version.

API

The package exports:

import {
  KIconify,
  registerIconPack,
  unregisterIconPack,
  getAllPackages,
  getAvailableIcons,
  getRawAvailableIcons,
  findSimilarIcons,
  getPackageInfo
} from 'kiconify'

registerIconPack

Register an icon collection manually:

registerIconPack('solar', solarIcons)

unregisterIconPack

Remove a registered collection:

unregisterIconPack('solar')

getAllPackages

Get the names of all registered collections:

getAllPackages()

getAvailableIcons

Get the available icon names in a collection:

getAvailableIcons('solar')

getRawAvailableIcons

Get the original exported component names from a collection:

getRawAvailableIcons('solar')

findSimilarIcons

Search for icon names similar to a given term:

findSimilarIcons('solar', 'home')

getPackageInfo

Get metadata for a registered collection when metadata is available:

getPackageInfo('solar')

Requirements

• Vue 3
• A Vite-based Vue application for the build-time optimization plugin
• Iconify prerendered Vue collections for the icon sets you want to use

License

MIT

Author

Kiyarash Hassanzadeh