Plugin System

PikaCSS provides a powerful plugin system that allows you to extend its functionality. This guide covers the basics of using plugins.

TIP

For advanced topics like creating custom plugins, plugin hooks, and TypeScript module augmentation, see the Advanced section.

Overview

The PikaCSS plugin system is built around the concept of hooks that allow plugins to interact with different stages of the CSS generation process.

Core Plugins

PikaCSS comes with several built-in core plugins that provide essential functionality:

Plugin	Purpose	Documentation
variables	Manages CSS custom properties	Variables
keyframes	Processes @keyframes animations	Keyframes
selectors	Handles custom selector transformations	Selectors
shortcuts	Manages style shortcuts	Shortcuts
important	Handles !important declarations	Important

These plugins are automatically loaded and configured through the engine configuration.

Using Plugins

To use a plugin, add it to the plugins array in your PikaCSS configuration:

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

export default defineEngineConfig({
	plugins: [
		icons() // Add icon support
	]
})

WARNING

Don't forget to call the plugin function! A common mistake is writing plugins: [icons] instead of plugins: [icons()].

Plugin Configuration

Many plugins accept configuration options. Plugin-specific configs are placed at the root level of the configuration:

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

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

	// Plugin configuration at root level
	icons: {
		prefix: 'i-',
		scale: 1.2
	}
})

Official Plugins

Reset Plugin

The @pikacss/plugin-reset package provides a modern CSS reset.

npm install -D @pikacss/plugin-reset

import { reset } from '@pikacss/plugin-reset'

export default defineEngineConfig({
	plugins: [reset()],
	reset: 'modern-normalize'
})

See the Reset Plugin documentation for more details.

Icons Plugin

The @pikacss/plugin-icons package provides icon support via Iconify.

npm install -D @pikacss/plugin-icons

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

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

See the Icons Plugin documentation for more details.

Typography Plugin

The @pikacss/plugin-typography package provides beautiful typographic defaults for prose content.

npm install -D @pikacss/plugin-typography

import { typography } from '@pikacss/plugin-typography'

export default defineEngineConfig({
	plugins: [
		typography() // Note: must call function
	],
	typography: {
		variables: {
			'--pk-prose-color-body': '#374151',
			'--pk-prose-color-headings': '#111827',
		}
	}
})

The plugin provides modular shortcuts like prose-base, prose-headings, prose-code, etc., that you can mix and match:

<!-- Use all typography styles -->
<article class="prose">...</article>

<!-- Or compose specific modules -->
<article class="prose-base prose-headings prose-paragraphs">...</article>

See the Typography Plugin documentation for more details.

Plugin Lifecycle

Plugins interact with the engine through hooks at different stages:

1. Configuration Phase: Plugins can modify the raw and resolved configuration
2. Setup Phase: Plugins can configure the engine instance (add shortcuts, selectors, etc.)
3. Transform Phase: Plugins can transform selectors, style items, and style definitions
4. Event Phase: Plugins can react to style changes and updates

Plugin Order

Plugins can specify an execution order:

• 'pre': Runs before default-order plugins
• undefined: Runs in normal order (default)
• 'post': Runs after default-order plugins

This allows you to control when your plugin runs relative to other plugins.

Learn More

• Plugin Development - Create your own plugins
• Plugin Hooks Reference - Complete hook documentation
• Module Augmentation - Extend PikaCSS types
• API Reference - Full API documentation