PikaCSS

Appearance

FAQ ​

Common questions and solutions for PikaCSS.

Why are my styles not appearing? ​

Make sure your application entry point imports the generated CSS module:

ts
// main.ts
import 'pika.css'

import 'pika.css' resolves to the configured CSS codegen output. By default that file is pika.gen.css.

If you are using the Nuxt module, the import is injected automatically. With the generic unplugin integration, make sure you add the import yourself and that the plugin is registered in your build config.

Why do I get "no-dynamic-args" ESLint errors? ​

The pikacss/no-dynamic-args rule requires each argument passed to pika() to stay within a recursively statically analyzable literal structure. Plain literals, static template literals, and nested object/array literals are fine; runtime variables, conditionals, function calls, and template expressions are not. Extract the dynamic part into separate pika() calls and combine the resulting class names at the call site:

ts
// ❌ Invalid — conditional argument
pika(isDark ? { color: 'white' } : { color: 'black' })

// ✅ Valid — separate calls, combine at call site
const className = isDark
  ? pika({ color: 'white' })
  : pika({ color: 'black' })

How do I change the layer order? ​

Define a custom layers map in your engine config. Lower numbers render earlier:

ts
import { defineEngineConfig } from '@pikacss/core'

export default defineEngineConfig({
  layers: {
    reset: -1,
    preflights: 1,
    components: 5,
    utilities: 10,
  },
})

See Layers for a full example.

Can I use PikaCSS without a build plugin? ​

Yes. @pikacss/core works without a bundler plugin. Create an engine, register styles with await engine.use(...), then compose the CSS output from the layer declaration, preflights, and atomic styles:

ts
import { createEngine, defineEngineConfig } from '@pikacss/core'

const engine = await createEngine(defineEngineConfig({}))
const atomicStyleIds = await engine.use({ color: 'red' })

const css = [
	engine.renderLayerOrderDeclaration(),
	await engine.renderPreflights(true),
	await engine.renderAtomicStyles(true, { atomicStyleIds }),
]
	.filter(Boolean)
	.join('\n\n')

The unplugin integration adds HMR and static extraction but is not required. The Nuxt module also auto-injects the CSS import, while the generic unplugin integrations still expect you to add import 'pika.css' yourself.

How do I add a custom pseudo-class or breakpoint? ​

Use the selectors config property to register custom selectors, including pseudo-classes and media-query responsive breakpoints:

ts
import { defineEngineConfig } from '@pikacss/core'

export default defineEngineConfig({
  selectors: {
    definitions: [
      ['@dark', 'html.dark $'],
      ['@sm', '@media (min-width: 640px)'],
    ],
  },
})

See Selectors.

TypeScript cannot find module augmentations from a plugin ​

Ensure the plugin package is installed and that your tsconfig.json uses a modern module resolution mode such as moduleResolution: 'bundler' or 'node16' so TypeScript can follow the plugin package export map to its declaration file and @pikacss/core module augmentation:

json
{
  "compilerOptions": {
    "moduleResolution": "bundler"
  }
}

Styles are not updating during development (HMR) ​

The PikaCSS Vite plugin handles HMR automatically. If styles are not updating:

  1. Verify the plugin is registered in vite.config.ts with PikaCSS().
  2. Check that import 'pika.css' is present in your entry file.
  3. Changing pika.config.ts should trigger a config reload automatically. If it does not, confirm you are editing the resolved config file path and that the saved file content actually changed.

How do I combine PikaCSS classes conditionally? ​

By default, transformed pika() calls produce a plain class name string, so standard JavaScript composition works:

ts
const base = pika({ display: 'flex', padding: '1rem' })
const active = pika({ color: 'blue' })
const inactive = pika({ color: 'gray' })

const className = `${base} ${isActive ? active : inactive}`

If your integration uses transformedFormat: 'array', normal pika() calls return arrays instead. pika.arr() also forces array output, so compose those results with your framework's usual array-based class handling.

Next ​