or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-unocss--transformer-variant-group

Variant group transformer for UnoCSS that enables Windi CSS variant group syntax, allowing developers to write more concise utility classes by grouping modifiers with parentheses.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@unocss/transformer-variant-group@66.5.x

To install, run

npx @tessl/cli install tessl/npm-unocss--transformer-variant-group@66.5.0

index.mddocs/

@unocss/transformer-variant-group

@unocss/transformer-variant-group is a UnoCSS transformer that enables Windi CSS variant group syntax, allowing developers to write more concise utility classes by grouping modifiers with parentheses. It transforms grouped syntax like hover:(bg-gray-400 font-medium) into expanded utility classes hover:bg-gray-400 hover:font-medium, reducing repetition and improving readability in CSS utility frameworks.

Package Information

  • Package Name: @unocss/transformer-variant-group
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install -D @unocss/transformer-variant-group

Core Imports

import transformerVariantGroup from '@unocss/transformer-variant-group';
import type { TransformerVariantGroupOptions } from '@unocss/transformer-variant-group';

For CommonJS:

const transformerVariantGroup = require('@unocss/transformer-variant-group');

Basic Usage

import transformerVariantGroup from '@unocss/transformer-variant-group';
import { defineConfig } from 'unocss';

export default defineConfig({
  // Other UnoCSS configuration
  transformers: [
    transformerVariantGroup(),
  ],
});

With custom separators:

import transformerVariantGroup from '@unocss/transformer-variant-group';

export default defineConfig({
  transformers: [
    transformerVariantGroup({
      separators: [':'], // Only colon, more strict than default
    }),
  ],
});

Capabilities

Transformer Factory Function

Creates a UnoCSS source code transformer that expands variant group syntax into individual utility classes.

/**
 * Creates a UnoCSS source code transformer for variant group expansion
 * @param options - Configuration for the transformer, defaults to empty object
 * @returns SourceCodeTransformer instance for use in UnoCSS configuration
 */
function transformerVariantGroup(
  options: TransformerVariantGroupOptions = {}
): SourceCodeTransformer;

export interface TransformerVariantGroupOptions {
  /**
   * Separators to expand.
   * 
   * ```
   * foo-(bar baz) -> foo-bar foo-baz
   *    ^
   *    separator
   * ```
   * 
   * You may set it to [':'] for strictness.
   * 
   * @default [':', '-']
   */
  separators?: (':' | '-')[];
}

Usage Examples:

// Default configuration (supports both : and - separators)
transformerVariantGroup()

// Strict configuration (only colon separator)
transformerVariantGroup({
  separators: [':']
})

// Custom configuration (only dash separator)
transformerVariantGroup({
  separators: ['-']
})

Types

interface SourceCodeTransformer {
  /** Name of the transformer */
  name: string;
  /** The order of transformer execution */
  enforce?: SourceCodeTransformerEnforce;
  /** Custom id filter, if not provided, the extraction filter will be applied */
  idFilter?: (id: string) => boolean;
  /** The transform function */
  transform: (
    code: MagicString,
    id: string,
    ctx: UnocssPluginContext
  ) => Awaitable<{ highlightAnnotations?: HighlightAnnotation[] } | void>;
}

type SourceCodeTransformerEnforce = 'pre' | 'post' | 'default';

interface HighlightAnnotation {
  /** Character offset in source code */
  offset: number;
  /** Length of the highlighted text */
  length: number;
  /** The class name being highlighted */
  className: string;
}

Transformation Examples

The transformer converts variant group syntax to expanded utility classes:

Basic variant groups:

<!-- Input -->
<div class="hover:(bg-gray-400 font-medium)" />

<!-- Output -->
<div class="hover:bg-gray-400 hover:font-medium" />

Nested variant groups:

<!-- Input -->
<div class="sm:(p-1 p-2)" />

<!-- Output -->
<div class="sm:p-1 sm:p-2" />

Complex nested groups:

<!-- Input -->
<div class="dark:lg:(p-1 p-2)" />

<!-- Output -->
<div class="dark:lg:p-1 dark:lg:p-2" />

Important modifiers:

<!-- Input -->
<div class="!hover:(m-2 p-2)" />
<div class="hover:(!m-2 p-2)" />

<!-- Output -->
<div class="!hover:m-2 !hover:p-2" />
<div class="hover:!m-2 hover:p-2" />

Complex selectors:

<!-- Input -->
<div class="[&]:(w-4 h-4)" />

<!-- Output -->
<div class="[&]:w-4 [&]:h-4" />

Edge Cases and Limitations

The transformer has built-in protections against transforming non-CSS syntax:

  • Arrow functions: hover:(param) => {} is ignored
  • Regular expressions: /-(\w)/g patterns are ignored
  • Empty groups: hover:() remains unchanged
  • Whitespace handling: Supports multiline groups with proper whitespace parsing
  • Depth limiting: Nested transformations are limited to prevent infinite recursion (default depth: 5)

Integration

  • Integrates with UnoCSS configuration system via the transformers array
  • Runs during the "pre" phase before other transformers
  • Works with any CSS class extraction method used by UnoCSS
  • Provides highlight annotations for development tools and IDE integration
  • Compatible with all UnoCSS presets and other transformers