tessl/npm-unplugin-icons

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

—

Pending

Overview

Eval results

Files

Component Resolver

Name: tessl/npm-unplugin-icons
Author: tessl

Automatic component resolution for unplugin-vue-components and unplugin-auto-import integration, enabling automatic component registration and importing.

Capabilities

ComponentsResolver Function

Main resolver function for automatic component registration.

/**
 * Resolver for unplugin-vue-components and unplugin-auto-import
 * @param options - Configuration options for the resolver
 * @returns Resolver function that maps component names to import paths
 */
function ComponentsResolver(options?: ComponentResolverOption): (name: string) => string | undefined;

ComponentResolverOption Interface

Configuration options for customizing component resolution behavior.

/**
 * Configuration options for ComponentsResolver
 */
interface ComponentResolverOption {
  /** Prefix for resolving components name. Set '' to disable prefix (default: 'i') */
  prefix?: string | false;
  
  /** Iconify collection names to enable for resolving (default: all collections) */
  enabledCollections?: string | string[];
  
  /** Icon collections aliases. The keys are aliases, values are collection names */
  alias?: Record<string, string>;
  
  /** Name for custom collections provided by loaders */
  customCollections?: string | string[];
  
  /** Extension for the resolved id. Set 'jsx' for JSX components (default: '') */
  extension?: string;
  
  /** @deprecated renamed to `prefix` */
  componentPrefix?: string;
  
  /** For collections strict matching. Set true to enable strict matching with '-' suffix */
  strict?: boolean;
}

Usage Examples

Basic Setup with unplugin-vue-components

import { defineConfig } from "vite";
import Vue from "@vitejs/plugin-vue";
import Icons from "unplugin-icons/vite";
import IconsResolver from "unplugin-icons/resolver";
import Components from "unplugin-vue-components/vite";

export default defineConfig({
  plugins: [
    Vue(),
    Icons({
      compiler: "vue3",
    }),
    Components({
      resolvers: [IconsResolver()],
    }),
  ],
});

Custom Prefix Configuration

import IconsResolver from "unplugin-icons/resolver";
import Components from "unplugin-vue-components/vite";

export default {
  plugins: [
    Components({
      resolvers: [
        // Default prefix 'i' -> <i-carbon-accessibility />
        IconsResolver(),
        
        // Custom prefix 'icon' -> <icon-carbon-accessibility />
        IconsResolver({ prefix: "icon" }),
        
        // No prefix -> <carbon-accessibility />
        IconsResolver({ prefix: false }),
      ],
    }),
  ],
};

Collection Filtering

import IconsResolver from "unplugin-icons/resolver";

export default {
  plugins: [
    Components({
      resolvers: [
        // Only enable specific collections
        IconsResolver({
          enabledCollections: ["carbon", "mdi", "heroicons"],
        }),
        
        // Single collection
        IconsResolver({
          enabledCollections: "carbon",
        }),
      ],
    }),
  ],
};

Collection Aliases

import IconsResolver from "unplugin-icons/resolver";

export default {
  plugins: [
    Components({
      resolvers: [
        IconsResolver({
          alias: {
            // Use <i-park-abnormal /> instead of <i-icon-park-abnormal />
            park: "icon-park",
            // Use <i-hi-heart /> instead of <i-heroicons-heart />
            hi: "heroicons",
            // Use <i-md-star /> instead of <i-mdi-star />
            md: "mdi",
          },
        }),
      ],
    }),
  ],
};

Custom Collections Integration

import IconsResolver from "unplugin-icons/resolver";
import Icons from "unplugin-icons/vite";
import { FileSystemIconLoader } from "unplugin-icons/loaders";

export default {
  plugins: [
    Icons({
      customCollections: {
        'brand': FileSystemIconLoader('./src/assets/brand-icons'),
        'ui': FileSystemIconLoader('./src/assets/ui-icons'),
      },
    }),
    Components({
      resolvers: [
        IconsResolver({
          customCollections: ["brand", "ui"],
        }),
      ],
    }),
  ],
};

JSX/React Setup

import IconsResolver from "unplugin-icons/resolver";
import Icons from "unplugin-icons/vite";

export default {
  plugins: [
    Icons({
      compiler: "jsx",
      jsx: "react",
    }),
    // For unplugin-auto-import with React
    AutoImport({
      resolvers: [
        IconsResolver({
          prefix: "Icon",
          extension: "jsx",
        }),
      ],
    }),
  ],
};

Strict Mode Configuration

import IconsResolver from "unplugin-icons/resolver";

export default {
  plugins: [
    Components({
      resolvers: [
        // Strict mode requires exact collection name matching with '-' suffix
        IconsResolver({
          strict: true,
        }),
      ],
    }),
  ],
};

Component Naming Patterns

Default Pattern (prefix: 'i')

<!-- Collection: carbon, Icon: accessibility -->
<i-carbon-accessibility />

<!-- Collection: mdi, Icon: heart -->
<i-mdi-heart />

<!-- Collection: heroicons, Icon: star -->
<i-heroicons-star />

Colon Syntax

<!-- Alternative syntax using colon separator -->
<i-carbon:accessibility />
<i-mdi:heart />
<i-heroicons:star />

With Aliases

// Configuration
IconsResolver({
  alias: {
    park: "icon-park",
    hi: "heroicons",
  },
})

<!-- Using aliases -->
<i-park-abnormal />  <!-- Instead of i-icon-park-abnormal -->
<i-hi-star />        <!-- Instead of i-heroicons-star -->

Custom Collections

// Configuration
IconsResolver({
  customCollections: ["brand", "ui"],
})

<!-- Using custom collections -->
<i-brand-logo />
<i-ui-button />

Advanced Integration Patterns

Multiple Resolvers

import IconsResolver from "unplugin-icons/resolver";
import Components from "unplugin-vue-components/vite";

export default {
  plugins: [
    Components({
      resolvers: [
        // Different configurations for different use cases
        IconsResolver({
          prefix: "icon",
          enabledCollections: ["carbon", "mdi"],
        }),
        IconsResolver({
          prefix: "hero",
          enabledCollections: ["heroicons"],
          strict: true,
        }),
      ],
    }),
  ],
};

TypeScript Integration

// For better TypeScript support, ensure proper type imports
import type { ComponentResolverOption } from "unplugin-icons/resolver";

const iconResolverConfig: ComponentResolverOption = {
  prefix: "i",
  enabledCollections: ["carbon", "mdi"],
  alias: { c: "carbon", m: "mdi" },
};

export default {
  plugins: [
    Components({
      resolvers: [IconsResolver(iconResolverConfig)],
    }),
  ],
};

Install with Tessl CLI