Selectors

Map short names to CSS selector patterns for concise nested style definitions.

Custom selectors let you define short, readable names for complex CSS selectors. Instead of writing full @media queries or compound selectors repeatedly, define them once and reference them by name in your style definitions.

The $ placeholder in a selector value is replaced with the generated atomic class selector.

Config

A selector definition accepts several shapes:

• Static tuple [name, cssSelector] — maps an exact name to one or more resolved CSS selectors.
• Dynamic tuple [RegExp, resolver, autocomplete?] — matches a pattern and computes the selector lazily. The optional third element lists autocomplete suggestions for the pattern (e.g. '@container-${name}'). The resolver may return undefined/null to signal "unresolved for now": nothing is cached and the rule is retried on a later resolve call.
• Object form — { selector, value } (static) or { selector, value, autocomplete? } (dynamic), equivalent to the tuples.
• Plain string — registers the name as an autocomplete suggestion only, useful for redirecting to a selector resolved elsewhere.

import { defineEngineConfig } from '@pikacss/core'

export default defineEngineConfig({
  selectors: {
    definitions: [
      // Static pair: [name, cssSelector]
      ['@dark', 'html.dark $'],
      ['@light', 'html:not(.dark) $'],

      // Media query selectors
      ['@sm', '@media (min-width: 640px)'],
      ['@md', '@media (min-width: 768px)'],
      ['@lg', '@media (min-width: 1024px)'],
      ['@xl', '@media (min-width: 1280px)'],

      // Dynamic pattern: [RegExp, resolver, autocomplete?]
      [/^@container-(.+)$/, ([, name]) => `@container ${name}`, '@container-${name}'],

      // Object form
      {
        selector: '@print',
        value: '@media print',
      },
    ],
  },
})

Use custom selectors in style definitions:

pika({
  'color': 'black',
  '@dark': { color: 'white' },
  '@sm': { fontSize: '14px' },
  '@lg': { fontSize: '18px' },
})

Examples

import { defineEngineConfig } from '@pikacss/core'

export const selectorsConfig = defineEngineConfig({
	selectors: {
		definitions: [
			['@dark', 'html.dark $'],
			['@light', 'html:not(.dark) $'],
			['@sm', '@media (min-width: 640px)'],
			['@md', '@media (min-width: 768px)'],
			['@lg', '@media (min-width: 1024px)'],
		],
	},
})

Next

• Shortcuts — create reusable style aliases.
• Variables — define CSS custom properties.