Icons

@pikacss/plugin-icons is the fastest way to pull large icon sets into the same build-time styling workflow as the rest of your PikaCSS system.

When to use it

Use the icons plugin when you want:

• icon names to behave like style-item strings
• zero runtime icon component overhead
• Iconify collection coverage
• CSS output that can still be themed through your existing styling model

Install

pnpm

pnpm add @pikacss/plugin-icons @iconify-json/mdi

npm

npm install @pikacss/plugin-icons @iconify-json/mdi

yarn

yarn add @pikacss/plugin-icons @iconify-json/mdi

Minimal setup

// pika.config.ts
import { icons } from '@pikacss/plugin-icons'
import { defineEngineConfig } from '@pikacss/unplugin-pikacss'

export default defineEngineConfig({
	plugins: [icons()],
	icons: {
		autoInstall: true,
	},
})

Usage

// pika() is available as a global function — no import needed

// Basic icon usage: prefix + collection:name
pika('i-mdi:home')
pika('i-mdi:account')
pika('i-lucide:settings')

// Force mask mode (icon inherits text color via currentColor)
pika('i-mdi:home?mask')

// Force background mode (icon keeps original colors)
pika('i-mdi:home?bg')

// Auto mode (default): uses mask if SVG contains currentColor, otherwise bg
pika('i-mdi:home?auto')

<template>
	<div>
		<!-- Basic icon -->
		<span :class="pika('i-mdi:home')" />

		<!-- Force mask mode: icon color follows text color -->
		<span
			:class="pika('i-mdi:account?mask')"
			style="color: red;"
		/>

		<!-- Force bg mode: icon keeps its original SVG colors -->
		<span :class="pika('i-mdi:palette?bg')" />
	</div>
</template>

Naming model

The default naming pattern uses the i- prefix plus collection:name, for example i-mdi:home.

This is valuable because icons become part of the same static authoring surface as shortcuts and selectors. Teams can review them as plain source strings instead of a separate runtime component system.

Do and do not

Do	Do not
Install the icon collections you actually use.	Assume every remote icon will always resolve in CI without configuration.
Keep icon naming conventions consistent across the project.	Mix several prefixes and ad hoc conventions without reason.
Use autocomplete for common icons.	Expect humans to remember hundreds of icon names accurately.

Advanced customization

// pika.config.ts
import { icons } from '@pikacss/plugin-icons'
import { defineEngineConfig } from '@pikacss/unplugin-pikacss'

export default defineEngineConfig({
	plugins: [icons()],
	icons: {
		// Icon scale factor (default: 1)
		scale: 1.2,
		// Rendering mode: 'auto' | 'mask' | 'bg' (default: 'auto')
		mode: 'mask',
		// Shortcut prefix (default: 'i-')
		prefix: 'i-',
		// Resolve local Iconify JSON packages from the workspace root
		cwd: process.cwd(),
		// Auto-install icon packages on demand
		autoInstall: true,
		// Extra CSS properties applied to every icon
		extraProperties: {
			'display': 'inline-block',
			'vertical-align': 'middle',
		},
		// CSS unit for width/height (e.g., 'em', 'rem')
		unit: 'em',
		// CDN fallback for unresolved collections (optional)
		// cdn: 'https://cdn.example.com/icons/{collection}.json',
	},
})

// pika.config.ts
import { icons } from '@pikacss/plugin-icons'
import { defineEngineConfig } from '@pikacss/unplugin-pikacss'

export default defineEngineConfig({
	plugins: [icons()],
	icons: {
		collections: {
			// Inline SVG collection
			custom: {
				logo: '<svg viewBox="0 0 24 24"><circle cx="12" cy="12" r="10" fill="currentColor"/></svg>',
			},
		},
	},
})
// Usage: pika('i-custom:logo')

If you want to keep your own SVG files in the repository, you can point a custom collection at a directory and keep using the same i-collection:name naming model.

This uses Iconify's filesystem loader, so it should be configured in a Node-based build environment such as Vite, Nuxt, or the PikaCSS CLI.

// pika.config.ts
import { FileSystemIconLoader } from '@iconify/utils/lib/loader/node-loaders'
import { icons } from '@pikacss/plugin-icons'
import { defineEngineConfig } from '@pikacss/unplugin-pikacss'

export default defineEngineConfig({
	plugins: [icons()],
	icons: {
		collections: {
			custom: FileSystemIconLoader('./src/assets/icons'),
		},
	},
})
// Usage: pika('i-custom:logo') -> ./src/assets/icons/logo.svg

Next

• Reset
• Typography
• Create A Plugin
• Configuration