0
# Variant Processing
1

2
Processes attributify selectors with variants like pseudo-classes, responsive breakpoints, and other UnoCSS variants, converting attribute-based variants into standard UnoCSS utility format.
3

4
## Capabilities
5

6
### Variant Function
7

8
Creates a variant handler for processing attributify selectors with UnoCSS variants.
9

10
```typescript { .api }
11
/**
12
 * Creates a variant handler for processing attributify selectors
13
 * @param options - Configuration options for variant processing
14
 * @returns UnoCSS VariantObject
15
 */
16
function variantAttributify(options: AttributifyOptions = {}): VariantObject;
17

18
interface VariantObject {
19
  name: 'attributify';
20
  match(input: string, context: VariantContext): string | VariantMatch[] | undefined;
21
}
22

23
interface VariantContext {
24
  generator?: UnoGenerator;
25
}
26

27
interface VariantMatch {
28
  matcher: string;
29
}
30
```
31

32
**Usage Examples:**
33

34
```typescript
35
import { variantAttributify } from '@unocss/preset-attributify'
36

37
// Create variant handler with default options
38
const variant = variantAttributify()
39

40
// Create variant handler with custom options  
41
const customVariant = variantAttributify({
42
  prefix: 'ui-',
43
  prefixedOnly: true,
44
  trueToNonValued: true
45
})
46
```
47

48
### Variants Regex
49

50
Regular expression for parsing variant prefixes from attribute values.
51

52
```typescript { .api }
53
/**
54
 * Regular expression for parsing variants from attribute values
55
 * Matches variant prefixes like "hover:", "sm:", etc.
56
 * Pattern: /^(?!.*\[[^:]+:.+\]$)((?:.+:)?!?)(.*)$/
57
 */
58
const variantsRE: RegExp;
59
```
60

61
### Variant Processing Logic
62

63
The variant handler processes attributify selectors through these steps:
64

65
1. **Selector Validation**: Checks if input is a valid attributify selector
66
2. **Prefix Handling**: Strips or validates attribute prefixes
67
3. **Variant Parsing**: Extracts variant prefixes from attribute values
68
4. **Self-Reference Expansion**: Handles special `~` syntax for attribute names
69
5. **Ambiguity Resolution**: Handles ambiguous variant/value combinations
70

71
### Selector Patterns
72

73
The variant handler processes these selector patterns:
74

75
**Basic Attributify Selector:**
76
```typescript
77
// Input: [bg~="blue-500"]
78
// Output: "bg-blue-500"
79
```
80

81
**With Variants:**
82
```typescript
83
// Input: [bg~="hover:blue-500"]  
84
// Output: "hover:bg-blue-500"
85
```
86

87
**Self-Reference:**
88
```typescript
89
// Input: [hover~="~"]
90
// Output: "hover:hover" (attribute name becomes utility)
91
```
92

93
**Non-Valued Attributes:**
94
```typescript
95
// Input: [mt-2=""]
96
// Output: "mt-2"
97

98
// With trueToNonValued: true
99
// Input: [mt-2="true"] 
100
// Output: "mt-2"
101
```
102

103
**Complex Variants:**
104
```typescript
105
// Input: [text~="sm:hover:red-500"]
106
// Output: "sm:hover:text-red-500"
107
```
108

109
### Ambiguity Resolution
110

111
The variant handler resolves ambiguous cases where variants and values could be interpreted multiple ways:
112

113
**Numeric Values with Variants:**
114
```html
115
<!-- Ambiguous: border="red:10" -->
116
<!-- Could be: border-red:10 OR red:border-10 -->
117
<div border="red:10"></div>
118
```
119

120
**Resolution Strategy:**
121
```typescript
122
// Returns both possibilities as VariantMatch[]
123
[
124
  { matcher: "red:border-10" },    // Variant interpretation
125
  { matcher: "border-red:10" }     // Value interpretation  
126
]
127
```
128

129
### Prefix Handling
130

131
The variant handler respects prefix configuration:
132

133
**With Prefix:**
134
```typescript
135
// options.prefix = "ui-"
136
// Input: [ui-bg~="blue-500"]
137
// Output: "bg-blue-500"
138

139
// options.prefixedOnly = true
140
// Input: [bg~="blue-500"] (no prefix)
141
// Output: undefined (ignored)
142
```
143

144
### Self-Reference Syntax
145

146
Special handling for the `~` self-reference syntax:
147

148
```html
149
<!-- Attribute name becomes the utility -->
150
<div hover="~"></div>        <!-- hover:hover -->
151
<div focus="~"></div>        <!-- focus:focus -->
152
<div bg="red-500 hover:~"></div>  <!-- bg-red-500 hover:bg -->
153
```
154

155
### Bracket Value Processing
156

157
Handles bracket notation for arbitrary values:
158

159
```typescript
160
// Input: [w~="[200px]"]
161
// Output: "w-[200px]"
162

163
// With variants
164
// Input: [w~="sm:[200px]"]  
165
// Output: "sm:w-[200px]"
166
```
167

168
### Complex Variant Examples
169

170
**Responsive Breakpoints:**
171
```html
172
<div text="sm:lg md:xl lg:2xl"></div>
173
```
174
Generates:
175
- `sm:text-lg`
176
- `md:text-xl` 
177
- `lg:text-2xl`
178

179
**Pseudo-Classes:**
180
```html
181
<div bg="blue-500 hover:blue-600 focus:blue-700"></div>
182
```
183
Generates:
184
- `bg-blue-500`
185
- `hover:bg-blue-600`
186
- `focus:bg-blue-700`
187

188
**Combined Variants:**
189
```html
190
<div text="sm:hover:red-500 lg:focus:blue-500"></div>
191
```
192
Generates:
193
- `sm:hover:text-red-500`
194
- `lg:focus:text-blue-500`
195

196
**Dark Mode:**
197
```html
198
<div bg="white dark:black text="black dark:white"></div>
199
```
200
Generates:
201
- `bg-white`
202
- `dark:bg-black`
203
- `text-black`
204
- `dark:text-white`
205

206
### Error Handling
207

208
The variant handler handles these edge cases:
209

210
- Invalid attributify selectors (returns `undefined`)
211
- Missing or malformed variant syntax
212
- Conflicting prefix requirements
213
- Invalid bracket notation
214
- Circular self-references
215

216
### Integration with UnoCSS
217

218
The variant handler integrates with UnoCSS's variant system:
219

220
```typescript
221
// Part of preset configuration
222
{
223
  variants: [variantAttributify(options)]
224
}
225
```
226

227
The handler works alongside other UnoCSS variants and respects the global variant configuration.