0
# Parser System
1

2
WindiCSS provides comprehensive parsing capabilities for HTML, CSS, and utility class names. The parser system enables extraction of classes from various sources, processing of CSS with WindiCSS features, and structured parsing of utility class names with variants.
3

4
## Capabilities
5

6
### HTMLParser
7

8
Parses HTML content to extract classes, attributes, and tags with position tracking.
9

10
```typescript { .api }
11
/**
12
 * Creates an HTML parser instance
13
 * @param html - Optional HTML content to parse
14
 */
15
constructor(html?: string);
16

17
/**
18
 * Parses HTML attributes from the content
19
 * @returns Array of attribute objects with metadata
20
 */
21
parseAttrs(): Attr[];
22

23
/**
24
 * Parses class attributes from HTML content, supports template literals
25
 * @returns Array of class name objects with position information
26
 */
27
parseClasses(): ClassName[];
28

29
/**
30
 * Extracts all HTML tag names from the content
31
 * @returns Array of unique tag names
32
 */
33
parseTags(): string[];
34
```
35

36
**Usage Examples:**
37

38
```typescript
39
import { HTMLParser } from "windicss/utils/parser";
40

41
// Parse HTML for classes
42
const html = '<div class="bg-blue-500 text-white p-4">Content</div>';
43
const parser = new HTMLParser(html);
44

45
const classes = parser.parseClasses();
46
// Returns: [{ result: "bg-blue-500 text-white p-4", start: 12, end: 36 }]
47

48
const attributes = parser.parseAttrs();
49
// Returns all attributes with position tracking
50

51
const tags = parser.parseTags();
52
// Returns: ["div"]
53
```
54

55
### CSSParser
56

57
Parses CSS content with full support for WindiCSS directives, theme functions, and nested styles.
58

59
```typescript { .api }
60
/**
61
 * Creates a CSS parser instance
62
 * @param css - Optional CSS content to parse
63
 * @param processor - Optional WindiCSS processor for advanced features
64
 */
65
constructor(css?: string, processor?: Processor);
66

67
/**
68
 * Parses CSS content into structured StyleSheet
69
 * @param css - CSS string to parse (defaults to instance CSS)
70
 * @param parent - Parent selector or at-rule for nested parsing
71
 * @param parentType - Type of parent context
72
 * @returns StyleSheet containing parsed styles
73
 */
74
parse(css?: string, parent?: string, parentType?: 'atRule' | 'selector'): StyleSheet;
75
```
76

77
**Usage Examples:**
78

79
```typescript
80
import { CSSParser } from "windicss/utils/parser";
81
import Processor from "windicss";
82

83
// Parse CSS with WindiCSS features
84
const css = `
85
  .custom {
86
    @apply bg-blue-500 text-white;
87
    color: theme('colors.red.500');
88
  }
89
`;
90

91
const processor = new Processor();
92
const parser = new CSSParser(css, processor);
93
const styleSheet = parser.parse();
94

95
// Parse nested CSS
96
const nestedCSS = `
97
  .parent {
98
    .child { color: red; }
99
  }
100
`;
101
const nestedStyles = parser.parse(nestedCSS);
102
```
103

104
### ClassParser
105

106
Parses utility class names into structured elements with variant support and grouping.
107

108
```typescript { .api }
109
/**
110
 * Creates a class parser instance
111
 * @param classNames - Space-separated class names string to parse
112
 * @param separator - Variant separator character (default: ':')
113
 * @param variants - Array of valid variant names
114
 */
115
constructor(classNames?: string, separator?: string, variants?: string[]);
116

117
/**
118
 * Parses class names into structured elements
119
 * @param removeDuplicated - Whether to remove duplicate class names
120
 * @returns Array of parsed element objects
121
 */
122
parse(removeDuplicated?: boolean): Element[];
123
```
124

125
**Usage Examples:**
126

127
```typescript
128
import { ClassParser } from "windicss/utils/parser";
129

130
// Parse utility classes with variants
131
const classNames = "hover:bg-blue-500 md:text-lg !important:p-4";
132
const variants = ["hover", "md", "important"];
133
const parser = new ClassParser(classNames, ":", variants);
134

135
const elements = parser.parse();
136
// Returns structured Element objects with variants and metadata
137

138
// Parse grouped classes
139
const groupedClasses = "hover:(bg-blue-500 text-white) md:p-4";
140
const groupParser = new ClassParser(groupedClasses);
141
const groupedElements = groupParser.parse();
142
```
143

144
## Types
145

146
```typescript { .api }
147
interface Attr {
148
  raw: string;              // Raw attribute string
149
  key: string;              // Attribute name
150
  value: string | string[]; // Attribute value(s)
151
  start: number;            // Start position in source
152
  end: number;              // End position in source
153
}
154

155
interface ClassName {
156
  result: string;  // Extracted class string content
157
  start: number;   // Start position in source
158
  end: number;     // End position in source
159
}
160

161
interface Element {
162
  raw: string;                         // Original raw class string
163
  start: number;                       // Start position in source
164
  end: number;                         // End position in source
165
  variants: string[];                  // Applied variants (e.g., ['hover', 'md'])
166
  content?: Element[] | string;        // Parsed content (nested for groups)
167
  func?: string;                       // Function name if applicable
168
  type: 'group' | 'func' | 'utility' | 'alias';  // Element type
169
  important: boolean;                  // Whether !important is applied
170
}
171

172
interface ParsedElement {
173
  tag: string;
174
  attributes: Attr[];
175
  children: ParsedElement[];
176
}
177

178
interface ParsedCSS {
179
  styles: Style[];
180
  variables: Record<string, unknown>;
181
}
182
```
183

184
## Integration with Processor
185

186
The parser system is tightly integrated with the WindiCSS Processor:
187

188
```typescript
189
import Processor from "windicss";
190

191
const processor = new Processor();
192

193
// HTMLParser integration - extract classes from HTML
194
const htmlClasses = processor.extract(htmlContent);
195

196
// ClassParser integration - used internally by processor methods
197
const result = processor.interpret("hover:bg-blue-500 md:text-lg");
198
// Uses ClassParser internally to parse class names
199

200
// CSSParser integration - process CSS with WindiCSS features
201
const styles = processor.preflight(htmlContent);
202
// Uses various parsers to extract and process content
203
```
204

205
## Advanced Usage
206

207
### Custom Variant Parsing
208

209
```typescript
210
import { ClassParser } from "windicss/utils/parser";
211

212
// Define custom variants
213
const customVariants = ["hover", "focus", "active", "custom"];
214
const parser = new ClassParser("custom:bg-red-500", ":", customVariants);
215
const elements = parser.parse();
216
```
217

218
### CSS Directive Processing
219

220
```typescript
221
import { CSSParser } from "windicss/utils/parser";
222
import Processor from "windicss";
223

224
const css = `
225
  .btn {
226
    @apply px-4 py-2 rounded;
227
    @variants hover, focus {
228
      @apply bg-blue-600;
229
    }
230
  }
231
`;
232

233
const processor = new Processor();
234
const parser = new CSSParser(css, processor);
235
const processed = parser.parse();
236
```
237

238
### HTML Attribute Extraction
239

240
```typescript
241
import { HTMLParser } from "windicss/utils/parser";
242

243
const html = `
244
  <div class="bg-blue-500" w:bg="red-500" data-theme="dark">
245
    <span className={clsx('text-white', isActive && 'font-bold')}>
246
      Content
247
    </span>
248
  </div>
249
`;
250

251
const parser = new HTMLParser(html);
252
const attrs = parser.parseAttrs();
253
// Extracts all attributes including WindiCSS attributify syntax