Plugin Icons API reference

Source information

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

Package summary

Icon shortcuts via Iconify

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

Functions

icons()

Creates the PikaCSS icons engine plugin.

Returns: EnginePlugin - An engine plugin that registers icon shortcut rules and autocomplete entries.

Remarks:

Resolves icon SVGs from custom collections, locally installed @iconify-json/* packages, or a remote CDN. 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'

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

Types

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 applied to the icon's intrinsic width and height. Combined with unit to produce the final CSS dimensions.	1
collections?	CustomCollections	Custom icon collections keyed by collection name. Each entry maps icon names to SVG strings or async loaders, checked before local packages and the CDN.	undefined
customizations?	IconCustomizations	Iconify customization hooks applied when loading icons. Allows transforming SVG attributes, trimming whitespace, and running per-icon logic via iconCustomizer.	{}
autoInstall?	IconifyLoaderOptions['autoInstall']	When enabled, automatically installs missing @iconify-json/* packages on demand during local icon resolution.	false
cwd?	IconifyLoaderOptions['cwd']	Working directory used by the Iconify node loader when resolving locally installed icon packages.	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 the icon's width and height (e.g. 'em', 'rem'). When set, produces explicit dimension values like 1em based on scale. When omitted, dimensions are left to the SVG's intrinsic size.	undefined
extraProperties?	Record<string, string>	Additional CSS properties merged into every generated icon style item. Useful for adding display, vertical-align, or other layout properties.	{}
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 resolved icon metadata, allowing custom property injection or conditional transformations.	undefined
autocomplete?	string[]	Explicit list of icon identifiers (e.g. 'mdi:home') to include in editor autocomplete suggestions. Each entry is combined with every configured prefix.	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, and finally from a CDN if configured.

import { defineEngineConfig } from '@pikacss/core'
import { icons } from '@pikacss/plugin-icons'

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

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