CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-unplugin-icons

Access thousands of icons as components on-demand universally across multiple build tools and frameworks

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

unplugin-icons

unplugin-icons is a universal icon solution that provides access to thousands of icons as components on-demand across multiple build tools and frameworks. It supports over 150 popular icon sets with more than 200,000 icons powered by Iconify, with on-demand bundling, SSR/SSG compatibility, and comprehensive TypeScript support.

Package Information

  • Package Name: unplugin-icons
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install unplugin-icons or pnpm add unplugin-icons

Core Imports

import Icons from "unplugin-icons/vite";
import { Options, CustomIconLoader, IconCustomizer, InlineCollection } from "unplugin-icons";

For specific build tools:

// Vite
import Icons from "unplugin-icons/vite";

// Webpack
import Icons from "unplugin-icons/webpack";

// Rollup
import Icons from "unplugin-icons/rollup";

// esbuild
import Icons from "unplugin-icons/esbuild";

// Rspack
import Icons from "unplugin-icons/rspack";

// Nuxt
import Icons from "unplugin-icons/nuxt";

For loaders, resolver, and utilities:

import { FileSystemIconLoader, ExternalPackageIconLoader } from "unplugin-icons/loaders";
import ComponentsResolver from "unplugin-icons/resolver";
import { collections, hasCollection } from "unplugin-icons/types";

Basic Usage

// vite.config.ts
import { defineConfig } from "vite";
import Icons from "unplugin-icons/vite";

export default defineConfig({
  plugins: [
    Icons({
      compiler: "vue3", // or 'react', 'svelte', etc.
      autoInstall: true,
    }),
  ],
});

Icon usage in components:

// React/JSX
import IconAccessibility from "~icons/carbon/accessibility";

function App() {
  return <IconAccessibility />;
}

// Vue 3
<template>
  <IconAccessibility />
</template>

<script setup>
import IconAccessibility from "~icons/carbon/accessibility";
</script>

// Svelte
<script>
import IconAccessibility from "~icons/carbon/accessibility";
</script>

<IconAccessibility />

Architecture

unplugin-icons is built around several key components:

  • Universal Plugin Core: Uses unplugin architecture to provide consistent API across all build tools
  • Icon Resolution System: Resolves virtual icon imports (~icons/collection/icon) to actual SVG content
  • Multi-Framework Compilers: Generates framework-specific components (React, Vue, Svelte, etc.) from SVG content
  • Custom Loaders: Supports loading icons from filesystem, external packages, or custom sources
  • Component Resolver: Integrates with unplugin-vue-components for automatic component registration
  • TypeScript Integration: Provides comprehensive type definitions for all supported frameworks

Capabilities

Plugin Configuration

Core plugin setup and configuration options for different build tools and frameworks.

interface Options {
  scale?: number;
  defaultStyle?: string;  
  defaultClass?: string;
  customCollections?: Record<string, CustomIconLoader | InlineCollection>;
  iconCustomizer?: IconCustomizer;
  collectionsNodeResolvePath?: string | string[];
  transform?: (svg: string, collection: string, icon: string) => Awaitable<string>;
  autoInstall?: boolean;
  compiler?: 'astro' | 'jsx' | 'marko' | 'none' | 'solid' | 'svelte' | 'raw' | 'vue2' | 'vue3' | 'web-components' | 'qwik' | CustomCompiler;
  jsx?: 'react' | 'preact' | 'qwik';
  webComponents?: WebComponentsConfig;
}

interface WebComponentsConfig {
  autoDefine?: boolean;
  iconPrefix?: string;
  shadow?: boolean;
}

Plugin Configuration

Icon Loaders

Custom icon loading functionality for filesystem icons, external packages, and custom icon sources.

function FileSystemIconLoader(
  dir: string, 
  transform?: (svg: string) => Awaitable<string>
): CustomIconLoader;

function ExternalPackageIconLoader(
  packageName: ExternalPkgName, 
  autoInstall?: AutoInstall
): Record<string, CustomIconLoader>;

type CustomIconLoader = (name: string) => Awaitable<string | undefined>;

Icon Loaders

Component Resolver

Automatic component resolution for unplugin-vue-components and unplugin-auto-import integration.

function ComponentsResolver(options?: ComponentResolverOption): (name: string) => string | undefined;

interface ComponentResolverOption {
  prefix?: string | false;
  enabledCollections?: string | string[];
  alias?: Record<string, string>;
  customCollections?: string | string[];
  extension?: string;
  strict?: boolean;
}

Component Resolver

Build Tool Integrations

Framework-specific plugin instances for different build tools and environments.

declare const VitePlugin: (options?: Options) => any;
declare const WebpackPlugin: (options?: Options) => any;
declare const RollupPlugin: (options?: Options) => any;
declare const EsbuildPlugin: (options?: Options) => any;
declare const RspackPlugin: (options?: Options) => any;
declare const NuxtModule: (options?: Options, nuxt?: any) => void;

Build Tool Integrations

Collections Utilities

Functions for working with available icon collections and validating collection names.

declare const collections: string[];

function hasCollection(collection: string): boolean;

Types

type IconCustomizer = (
  collection: string, 
  icon: string, 
  props: Record<string, string>
) => Awaitable<void>;

type InlineCollection = Record<string, string | (() => Awaitable<string | undefined>)>;

interface CustomCompiler {
  compiler: Awaitable<Compiler>;
  extension?: string;
}

type Compiler = (
  svg: string,
  collection: string,
  icon: string,
  options: ResolvedOptions
) => string | Promise<string>;

type ResolvedOptions = Omit<Required<Options>, 'iconSource' | 'transform'> & Pick<Options, 'transform'>;

// Utility types
type Awaitable<T> = T | Promise<T>;

// External types from @iconify/utils for ExternalPackageIconLoader
type ExternalPkgName = string;
type AutoInstall = boolean | { install?: boolean };
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/unplugin-icons@22.2.x
Publish Source
CLI
Badge
tessl/npm-unplugin-icons badge