0
# @unocss/transformer-variant-group
1

2
@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.
3

4
## Package Information
5

6
- **Package Name**: @unocss/transformer-variant-group
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install -D @unocss/transformer-variant-group`
10

11
## Core Imports
12

13
```typescript
14
import transformerVariantGroup from '@unocss/transformer-variant-group';
15
import type { TransformerVariantGroupOptions } from '@unocss/transformer-variant-group';
16
```
17

18
For CommonJS:
19

20
```javascript
21
const transformerVariantGroup = require('@unocss/transformer-variant-group');
22
```
23

24
## Basic Usage
25

26
```typescript
27
import transformerVariantGroup from '@unocss/transformer-variant-group';
28
import { defineConfig } from 'unocss';
29

30
export default defineConfig({
31
  // Other UnoCSS configuration
32
  transformers: [
33
    transformerVariantGroup(),
34
  ],
35
});
36
```
37

38
With custom separators:
39

40
```typescript
41
import transformerVariantGroup from '@unocss/transformer-variant-group';
42

43
export default defineConfig({
44
  transformers: [
45
    transformerVariantGroup({
46
      separators: [':'], // Only colon, more strict than default
47
    }),
48
  ],
49
});
50
```
51

52
## Capabilities
53

54
### Transformer Factory Function
55

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

58
```typescript { .api }
59
/**
60
 * Creates a UnoCSS source code transformer for variant group expansion
61
 * @param options - Configuration for the transformer, defaults to empty object
62
 * @returns SourceCodeTransformer instance for use in UnoCSS configuration
63
 */
64
function transformerVariantGroup(
65
  options: TransformerVariantGroupOptions = {}
66
): SourceCodeTransformer;
67

68
export interface TransformerVariantGroupOptions {
69
  /**
70
   * Separators to expand.
71
   * 
72
   * ```
73
   * foo-(bar baz) -> foo-bar foo-baz
74
   *    ^
75
   *    separator
76
   * ```
77
   * 
78
   * You may set it to [':'] for strictness.
79
   * 
80
   * @default [':', '-']
81
   */
82
  separators?: (':' | '-')[];
83
}
84
```
85

86
**Usage Examples:**
87

88
```typescript
89
// Default configuration (supports both : and - separators)
90
transformerVariantGroup()
91

92
// Strict configuration (only colon separator)
93
transformerVariantGroup({
94
  separators: [':']
95
})
96

97
// Custom configuration (only dash separator)
98
transformerVariantGroup({
99
  separators: ['-']
100
})
101
```
102

103
## Types
104

105
```typescript { .api }
106
interface SourceCodeTransformer {
107
  /** Name of the transformer */
108
  name: string;
109
  /** The order of transformer execution */
110
  enforce?: SourceCodeTransformerEnforce;
111
  /** Custom id filter, if not provided, the extraction filter will be applied */
112
  idFilter?: (id: string) => boolean;
113
  /** The transform function */
114
  transform: (
115
    code: MagicString,
116
    id: string,
117
    ctx: UnocssPluginContext
118
  ) => Awaitable<{ highlightAnnotations?: HighlightAnnotation[] } | void>;
119
}
120

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

123
interface HighlightAnnotation {
124
  /** Character offset in source code */
125
  offset: number;
126
  /** Length of the highlighted text */
127
  length: number;
128
  /** The class name being highlighted */
129
  className: string;
130
}
131
```
132

133
## Transformation Examples
134

135
The transformer converts variant group syntax to expanded utility classes:
136

137
**Basic variant groups:**
138
```html
139
<!-- Input -->
140
<div class="hover:(bg-gray-400 font-medium)" />
141

142
<!-- Output -->
143
<div class="hover:bg-gray-400 hover:font-medium" />
144
```
145

146
**Nested variant groups:**
147
```html
148
<!-- Input -->
149
<div class="sm:(p-1 p-2)" />
150

151
<!-- Output -->
152
<div class="sm:p-1 sm:p-2" />
153
```
154

155
**Complex nested groups:**
156
```html
157
<!-- Input -->
158
<div class="dark:lg:(p-1 p-2)" />
159

160
<!-- Output -->
161
<div class="dark:lg:p-1 dark:lg:p-2" />
162
```
163

164
**Important modifiers:**
165
```html
166
<!-- Input -->
167
<div class="!hover:(m-2 p-2)" />
168
<div class="hover:(!m-2 p-2)" />
169

170
<!-- Output -->
171
<div class="!hover:m-2 !hover:p-2" />
172
<div class="hover:!m-2 hover:p-2" />
173
```
174

175
**Complex selectors:**
176
```html
177
<!-- Input -->
178
<div class="[&]:(w-4 h-4)" />
179

180
<!-- Output -->
181
<div class="[&]:w-4 [&]:h-4" />
182
```
183

184
## Edge Cases and Limitations
185

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

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

194
## Integration
195

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