Icons

INFO

Big thanks to unocss for the icons preset that this plugin is based on. This icons plugin is a wrapper around it to adapt it to PikaCSS.

Check the documentation for more information about the icons available and how to use them.

Installation

pnpm

pnpm add -D @pikacss/plugin-icons

yarn

yarn add -D @pikacss/plugin-icons

npm

npm install -D @pikacss/plugin-icons

Setup

Vite Project

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

export default defineEngineConfig({
	plugins: [
		icons()  // Register plugin
	],
	icons: {
		// Configure options here
		scale: 1,
		mode: 'auto',
		prefix: 'i-',
	}
})

Nuxt Project

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

export default defineEngineConfig({
	plugins: [
		icons()  // Register plugin
	],
	icons: {
		// Configure options here
		scale: 1,
		mode: 'auto',
		prefix: 'i-',
	}
})

Usage

The icons would be provided as shortcuts, so you can use them like this:

pika('i-mdi:home')

Or use with __shortcut property:

pika({
	__shortcut: 'i-mdi:home'
})

Specifying Render Mode

Append ?mask or ?bg to force a specific rendering mode:

// Force mask mode (for colored icons)
pika('i-mdi:home?mask')

// Force background mode
pika('i-mdi:home?bg')

Configuration Options

The plugin configuration consists of two parts:

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

export default defineEngineConfig({
	// 1. Register plugin in the plugins array
	plugins: [
		icons()  // Must call the function
	],
	
	// 2. Configure options at root level
	icons: {
		// Icon scale multiplier (default: 1)
		scale: 1.2,

		// Rendering mode: 'auto' | 'mask' | 'bg' (default: 'auto')
		mode: 'auto',

		// Class prefix (default: 'i-')
		prefix: 'i-',

		// CDN URL for loading icons (optional)
		cdn: 'https://esm.sh/',

		// Extra CSS properties applied to all icons
		extraProperties: {
			'display': 'inline-block',
			'vertical-align': 'middle'
		},

		// Icons to include in autocomplete suggestions
		autocomplete: ['mdi:home', 'mdi:account', 'mdi:settings'],

		// Auto-install icon packages when encountered
		autoInstall: false,

		// CSS unit for icon size
		unit: 'em'
	}
})

Options Reference

Option	Type	Default	Description
scale	number	1	Icon size multiplier
mode	'auto' | 'mask' | 'bg'	'auto'	Default rendering mode
prefix	string	'i-'	Class name prefix
cdn	string	-	CDN URL for fetching icons
extraProperties	Record<string, string>	{}	Additional CSS properties
collections	Record<string, IconifyJSON | () => IconifyJSON>	-	Custom icon collections
customizations	IconCustomizations	-	Icon customization options
autoInstall	boolean	false	Auto-install icon packages
unit	string	'em'	CSS unit for icon size
autocomplete	string[]	-	Icons for autocomplete

Rendering Modes

Mode	Description	Use Case
auto	Automatically selects based on icon	Default behavior
mask	Uses CSS mask (icon inherits currentColor)	Monochrome icons
bg	Uses background-image	Multi-colored icons

Custom Icon Collections

You can define custom icon collections:

export default defineEngineConfig({
	plugins: [
		icons()
	],
	icons: {
		collections: {
			'my-icons': {
				logo: '<svg>...</svg>',
				custom: '<svg>...</svg>'
			}
		}
	}
})

// Usage: 'i-my-icons:logo'

How It Works

1. The plugin registers a dynamic shortcut that matches the icon pattern (e.g., i-mdi:home)
2. When matched, it loads the SVG from Iconify
3. The SVG is encoded as a Data URI and stored as a CSS variable
4. Returns a style object using mask or background to display the icon

External Resources

• Iconify Icon Sets - Browse all available icons
• UnoCSS preset-icons - Based on the same icon system