Plugin Icons API reference

Source information

• Package: @pikacss/plugin-icons
• Generated from the exported surface and JSDoc in packages/plugin-icons/src/index.ts.
• Public entries: @pikacss/plugin-icons, @pikacss/plugin-icons/node
• Source files: packages/plugin-icons/src/index.ts, packages/plugin-icons/src/node.ts, packages/plugin-icons/src/watchable.ts

Package summary

Icon shortcuts via Iconify.

Use Icons plugin when you need conceptual usage guidance instead of exact symbol lookup.

Functions

createIconsPlugin(runtime?)

Creates an icons plugin using host-provided runtime capabilities.

Parameter	Type	Description
runtime?	IconsRuntimeOptions	Optional host-provided runtime capabilities. This factory does not automatically provide the built-in Node.js loader; use @pikacss/plugin-icons/node for that adapter or provide the required capabilities explicitly here.

Returns: EnginePlugin - An engine plugin that resolves icon utilities into CSS styles.

defineWatchableIconCollection(options)

Declares a custom icon collection whose backing files PikaCSS watches.

Parameter	Type	Description
options	{ source: WatchableIconSource; dependencies: IconCollectionDependencies; }	The collection source plus its dependency declaration.
options.source	WatchableIconSource	The collection's icon source: an inline map or a loader receiving (name, sourceContext).
options.dependencies	IconCollectionDependencies	The external resources backing the collection's icons.

Returns: WatchableIconCollection - A branded descriptor accepted by icons.collections.

Remarks:

Ordinary CustomCollections entries stay fully supported and opaque — PikaCSS cannot infer files an arbitrary loader reads. Collection-wide static dependencies on this descriptor are registered during Engine initialization. Request-specific dependency functions resolve absolute paths and pass them to the loader. They become Engine dependencies only when an authoritative enumerable catalog identifies the corresponding concrete members during initialization; arbitrary request-only loaders remain non-exhaustive. Private caches inside a user-supplied loader remain outside PikaCSS's invalidation guarantee. Use a collection-wide catalog dependency when the loader is request-only and cannot enumerate every icon file; the dependency is watchable even though individual request paths are not.

Pass the returned descriptor through UNMODIFIED. Object spread copies the enumerable symbol brand initially, but it also turns the descriptor into a plain object; Core's #117 engine-config clone then copies only ordinary string entries and the private capability brand is lost. Create a new descriptor instead of copying one.

declare function readIconCatalog(path: string): Promise<Record<string, string>>

icons: {
  collections: {
    app: defineWatchableIconCollection({
      dependencies: './icons/catalog.json',
      source: async (name, { dependencies: [catalogFile] }) => {
        const catalog = await readIconCatalog(catalogFile)
        return catalog[name]
      },
    }),
  },
}

icons()

Creates the PikaCSS icons engine plugin.

Returns: EnginePlugin - An engine plugin that lowers one dynamic icon family into the Core Shortcuts subsystem.

Remarks:

The package-root icons() factory is platform-neutral: it resolves custom collections and remote CDN sources, but does not provide a local loader. The /node entry's icons() factory supplies PikaCSS's built-in Node.js loader for locally installed @iconify-json/* packages. Use createIconsPlugin(runtime) when a host needs to supply a different local loading capability. Each matched utility is expanded into a CSS style item using either mask or background rendering. Configure behavior through the icons key in your engine config.

import { icons } from '@pikacss/plugin-icons'
import { defineConfig } from '@pikacss/unplugin-pikacss'

export default defineConfig({
  engine: {
    plugins: [icons()],
    icons: { prefix: 'i-', mode: 'auto' },
  },
})

isWatchableIconCollection(value)

Type guard for WatchableIconCollection descriptors.

Internal API. Tagged @internal in the source: exported at runtime, but intended for PikaCSS's own packages and may change without notice.

Parameter	Type	Description
value	unknown	Any icons.collections entry.

Returns: value is WatchableIconCollection - Whether the value carries the watchable-collection brand.

Types

FileSystemIconCatalogEnumerator

Host capability for direct-member enumeration of built-in filesystem collections.

Type: (directory: string, extension: string) => Promise<readonly string[]>

IconCollectionDependencies

External resources that determine a watchable collection's resolved icons.

Type: string | string[] | ((context: WatchableIconCollectionContext) => Awaitable<string | string[]>)

Remarks:

A string or array declares collection-wide dependencies and is registered during Engine initialization. A function declares request-specific dependency paths evaluated before the icon loader runs. Enumerable built-in/inline catalogs can register the paths of members known during initialization; opaque request-only loaders receive their resolved paths as loader context only — those paths are not registered or watched after Engine initialization. Relative paths resolve from the engine host's effective project root (#118); absolute paths are used as-is.

IconsConfig

Configuration options for the PikaCSS icons plugin.

Property	Type	Description	Default
prefix?	string | string[]	One or more prefixes used to match icon utility names. When a utility matches <prefix><collection>:<name>, it resolves to an icon style.	'i-'
mode?	'auto' | 'mask' | 'bg'	Rendering strategy for icon SVGs. 'mask' uses a CSS mask with currentColor as the fill, allowing color inheritance. 'bg' renders the SVG as a background image with its original colors. 'auto' chooses 'mask' when the SVG contains currentColor, otherwise 'bg'.	'auto'
scale?	number	Multiplier passed to Iconify when unit is omitted, scaling the dimensions it resolves from the icon source. For Iconify JSON collections, that includes Iconify's 1em fallback when no dimensions are available. When unit is configured, the same scale supplies the numeric part of the explicit ${scale}${unit} dimensions described by unit.	1
collections?	Record<string, CustomIconLoader | InlineCollection | WatchableIconCollection>	Custom icon collections keyed by collection name. Each entry maps icon names to SVG strings or async loaders, checked before any active local loader and the CDN. Ordinary entries are opaque to PikaCSS — the files an arbitrary loader reads cannot be inferred. Wrap an entry with defineWatchableIconCollection to declare collection-wide filesystem dependencies, or per-icon dependencies for members enumerable during Engine initialization. Request-only dependency callbacks do not expand the finalized watcher later (#122).	undefined
customizations?	IconCustomizations	Iconify customization hooks applied when loading icons. Allows transforming SVG attributes, trimming whitespace, and running per-icon logic via iconCustomizer. The plugin's unit filler runs in that callback before Iconify applies additionalProps; extraProperties are merged into those additional properties after the configured customizations.additionalProps.	{}
autoInstall?	IconifyLoaderOptions['autoInstall']	When enabled, automatically installs missing @iconify-json/* packages on demand during local icon resolution. With cwd: string[], roots are searched in order; the built-in Iconify node loader passes autoInstall only for the final root, so earlier roots are lookup-only. Requires a local-loader capability such as @pikacss/plugin-icons/node; the platform-neutral package root does not install packages. With the built-in /node adapter, local loading (and therefore auto-install) is intentionally skipped while process.env.ESLINT is set.	false
cwd?	IconifyLoaderOptions['cwd']	Search root used by the Iconify node loader when resolving locally installed icon packages. Accepts a string or string[]; array entries are searched in order, and the built-in node loader only attempts autoInstall for the final entry. The host projectRoot is resolved to an absolute path first; relative entries resolve against it, and omitted cwd defaults to that root. Without a host projectRoot, standalone use defaults to the current working directory and the effective value is still absolute. Requires a local-loader capability such as @pikacss/plugin-icons/node, or a custom capability passed to createIconsPlugin(runtime).	undefined
cdn?	string	CDN URL template for fetching remote icon sets. Use {collection} as a placeholder for the collection name, or provide a base URL and the collection name will be appended as <url>/<collection>.json.	undefined
unit?	string	CSS unit appended to icon dimensions (e.g. 'em', 'rem'). After the user's iconCustomizer runs, the plugin fills each missing or falsy width/height with ${scale}${unit}. Iconify then applies customizations.additionalProps; extraProperties are merged after those values and therefore win on duplicate keys. Any remaining explicit dimension takes precedence over Iconify's source dimensions; if only one is present, Iconify derives the other from the SVG aspect ratio when it can. When omitted, Iconify uses the dimensions it resolves from the source and applies scale.	undefined
extraProperties?	Record<string, string>	Additional icon properties passed to Iconify and forwarded into every generated icon style item. They are merged after customizations.additionalProps, so duplicate keys—including width/height—use extraProperties.	{}
processor?	(styleItem: StyleItem, meta: Required<IconMeta>) => void	Post-processing callback invoked on each generated icon style item before it is returned. Receives the mutable style item and icon metadata. The metadata's name is the parsed/requested icon name carried through resolution; it is not guaranteed to be the canonical catalog key or an alias target.	undefined
autocomplete?	string[]	Explicit list of unprefixed logical icon identifiers (e.g. 'mdi:home'; omit the configured shortcut prefix) to add to editor autocomplete suggestions. Each entry is combined with every configured prefix. This list is additive. The built-in /node catalog discovery also contributes names from the nearest governing package.json for each search root, considering only dependencies, devDependencies, and optionalDependencies; peer dependencies and ancestor manifests are not catalog-completion sources.	undefined

Remarks:

Controls how icon utilities are resolved, loaded, and rendered as CSS. Icons are loaded from custom collections first, then from locally installed Iconify packages when a local-loader capability is active, and finally from a CDN if configured. The /node entry provides the built-in local loader; the package root remains platform-neutral.

import { icons } from '@pikacss/plugin-icons'
import { defineConfig } from '@pikacss/unplugin-pikacss'

export default defineConfig({
  engine: {
    plugins: [icons()],
    icons: {
      prefix: 'i-',
      mode: 'auto',
      scale: 1,
      cdn: 'https://esm.sh/@iconify-json/{collection}/icons.json',
    },
  },
})

IconsRuntimeOptions

Runtime capabilities used by the icons plugin.

Property	Type	Description	Default
loadLocalIcon?	LocalIconLoader	Optional loader for locally installed icon collections.	—
shouldLoadLocalIcon?	() => boolean	Determines whether the local loader should run for the current host context.	—
enumerateFileSystemIconNames?	FileSystemIconCatalogEnumerator	Node/host direct-member enumerator used only by the built-in filesystem catalog capability.	—
discoverLocalIconCatalog?	LocalIconCatalogDiscovery	Node/host discovery of directly declared Iconify logical identities for autocomplete.	—

LocalIconCatalogDiscovery

Host capability for discovering directly declared local Iconify catalogs.

Type: (cwd: string | readonly string[]) => Promise<LocalIconCatalogDiscoveryResult>

LocalIconCatalogDiscoveryResult

Logical catalog identities plus the files read to derive them.

Property	Type	Description	Default
identities	readonly string[]	Logical prefix:name identities discovered from directly declared Iconify catalogs.	—
dependencies	readonly string[]	Files read while discovering identities, including each root's governing manifest and catalog JSON files.	—

LocalIconLoader

Host capability loading an icon from a locally installed Iconify collection.

Type: (collection: string, name: string, options: IconifyLoaderOptions) => Promise<string | null | undefined>

WatchableIconCollection

A custom icon collection whose filesystem dependencies participate in PikaCSS dependency metadata (#122). Collection-wide dependencies participate in initialization-time watching; request-specific paths are registered only for members that an authoritative enumerable catalog discovers during initialization. Arbitrary request-only paths are passed to the loader but are never late-registered or watched.

Property	Type	Description	Default
source	WatchableIconSource	The collection's icon source (inline map or loader).	—
dependencies	IconCollectionDependencies	The external resources backing the collection's icons.	—

Remarks:

Create via defineWatchableIconCollection; the descriptor is configuration data and must be treated as immutable definition identity; pass it through unmodified and never spread it.

WatchableIconCollectionContext

Identifies which icon request a per-request dependency declaration is for.

Property	Type	Description	Default
collection	string	The collection name the request targets (the key in icons.collections).	—
name	string	The requested icon name inside the collection.	—

WatchableIconSource

A watchable collection's icon source: the existing custom-collection behavior (an inline icon map, or a loader from icon name to SVG), where a loader additionally receives the resolved dependency context.

Type: InlineCollection | ((name: string, context: WatchableIconSourceContext) => Awaitable<string | undefined>)

WatchableIconSourceContext

Context handed to a watchable collection's loader function.

Property	Type	Description	Default
projectRoot	string	The effective absolute project root; standalone use defaults to the current working directory.	—
dependencies	string[]	The request's declared dependencies, resolved to absolute paths, in declaration order.	—

Public subpath: @pikacss/plugin-icons/node

Import this entry as @pikacss/plugin-icons/node.

fileSystemIconCollection(options)

Creates a watchable icon collection backed by one directory of SVG files.

Parameter	Type	Description
options	{ dir: string; extension?: string; }	The backing directory and optional file extension.
options.dir	string	Directory holding one file per icon. Relative paths resolve from the engine host's effective absolute projectRoot; a missing host projectRoot defaults to the current working directory before resolution.
options.extension?	string	File extension appended to the icon name. Defaults to '.svg'.

Returns: WatchableIconCollection - A watchable collection descriptor for icons.collections.

Remarks:

i-app:home resolves <dir>/home.svg. The loader reads the backing SVG when that icon is resolved for an Engine generation, and a re-derived Engine does not reuse process-global Iconify collection cache state. Catalog derivation registers direct-member directory membership separately from each known icon file, so create/delete/rename and content/existence changes invalidate the project generation with the correct dependency semantics. The returned descriptor must be passed to icons.collections unmodified; do not copy it with object spread.

import { fileSystemIconCollection, icons } from '@pikacss/plugin-icons/node'
import { defineConfig } from '@pikacss/unplugin-pikacss'

export default defineConfig({
  engine: {
    plugins: [icons()],
    icons: { collections: { app: fileSystemIconCollection({ dir: './icons' }) } },
  },
})

icons()

Creates the built-in Node.js icons plugin with locally installed Iconify collection loading. Import this factory from @pikacss/plugin-icons/node; the package-root icons() factory is platform-neutral, while createIconsPlugin(runtime) is for custom host capabilities.

Returns: EnginePlugin<any> - An icons plugin configured with the Iconify Node.js loader.

Module augmentations

EngineConfig (@pikacss/core)

Property	Type	Description	Default
icons?	IconsConfig	Configuration for the icons plugin. Requires the icons() plugin to be registered in plugins for this configuration to take effect.	undefined

Next

• Icons plugin
• Plugin Fonts API reference
• API reference overview