0
# Autocomplete Support
1

2
Provides intelligent autocomplete for attributify syntax in IDEs and editors, enabling developers to get suggestions for attribute names and values while writing HTML.
3

4
## Capabilities
5

6
### Autocomplete Extractor Function
7

8
Creates an autocomplete extractor that provides intelligent suggestions for attributify syntax.
9

10
```typescript { .api }
11
/**
12
 * Creates an autocomplete extractor for IDE/editor support
13
 * @param options - Configuration options for autocomplete behavior
14
 * @returns UnoCSS AutoCompleteExtractor object
15
 */
16
function autocompleteExtractorAttributify(options?: AttributifyOptions): AutoCompleteExtractor;
17

18
interface AutoCompleteExtractor {
19
  name: 'attributify';
20
  extract(context: AutoCompleteContext): AutoCompleteResult | null;
21
}
22

23
interface AutoCompleteContext {
24
  content: string;
25
  cursor: number;
26
}
27

28
interface AutoCompleteResult {
29
  extracted: string;
30
  transformSuggestions?(suggestions: string[]): string[];
31
  resolveReplacement(suggestion: string): ReplacementResult;
32
}
33

34
interface ReplacementResult {
35
  start: number;
36
  end: number;  
37
  replacement: string;
38
}
39
```
40

41
**Usage Examples:**
42

43
```typescript
44
import { autocompleteExtractorAttributify } from '@unocss/preset-attributify'
45

46
// Create autocomplete extractor
47
const autoComplete = autocompleteExtractorAttributify({
48
  prefix: 'ui-',
49
  prefixedOnly: true
50
})
51

52
// Extract autocomplete information
53
const result = autoComplete.extract({
54
  content: '<div bg="blue-|">',  // | represents cursor position
55
  cursor: 15
56
})
57
```
58

59
### Autocomplete Context Detection
60

61
The extractor analyzes cursor position to determine the autocomplete context:
62

63
**Attribute Name Completion:**
64
```html
65
<!-- Cursor after "b" -->
66
<div b|></div>
67
<!-- Suggests: bg, border, etc. -->
68
```
69

70
**Attribute Value Completion:**
71
```html
72
<!-- Cursor after "blue-" -->
73
<div bg="blue-|"></div>
74
<!-- Suggests: blue-100, blue-200, blue-500, etc. -->
75
```
76

77
**Multi-Value Completion:**
78
```html
79
<!-- Cursor after space -->
80
<div bg="blue-500 |"></div>
81
<!-- Suggests additional background utilities -->
82
```
83

84
### Completion Types
85

86
The autocomplete system handles different completion scenarios:
87

88
**1. Attribute Name Suggestions:**
89
```typescript { .api }
90
// When cursor is on attribute name
91
interface AttributeNameCompletion extends AutoCompleteResult {
92
  extracted: string; // The partial attribute name (without prefix)
93
  resolveReplacement(suggestion: string): {
94
    start: number; // Start of attribute name (after prefix if any)
95
    end: number;   // End of attribute name
96
    replacement: string; // The suggested attribute name
97
  };
98
}
99
```
100

101
**2. Attribute Value Suggestions:**
102
```typescript { .api }
103
// When cursor is within attribute value
104
interface AttributeValueCompletion extends AutoCompleteResult {
105
  extracted: string; // Full utility with variants (e.g., "hover:bg-blue")
106
  transformSuggestions(suggestions: string[]): string[]; // Filters relevant suggestions
107
  resolveReplacement(suggestion: string): {
108
    start: number; // Start of current value
109
    end: number;   // End of current value  
110
    replacement: string; // The suggested value (without attribute name)
111
  };
112
}
113
```
114

115
### Prefix Handling
116

117
The autocomplete respects prefix configuration:
118

119
**With Prefix:**
120
```html
121
<!-- options.prefix = "ui-", prefixedOnly = true -->
122
<div ui-bg="|"></div>  <!-- Completes ui-bg attribute values -->
123
<div bg="|"></div>     <!-- No completion (not prefixed) -->
124
```
125

126
**Without Prefix Requirement:**
127
```html
128
<!-- options.prefixedOnly = false -->
129
<div bg="|"></div>     <!-- Completes bg attribute values -->
130
<div ui-bg="|"></div>  <!-- Also completes, strips ui- prefix -->
131
```
132

133
### Value Parsing and Completion
134

135
The autocomplete parses attribute values to provide contextual suggestions:
136

137
**Simple Values:**
138
```html
139
<div bg="blu|"></div>
140
<!-- Extracted: "bg-blu" -->
141
<!-- Suggestions: filtered to bg-blue-* utilities -->
142
```
143

144
**With Variants:**
145
```html
146
<div bg="hover:blu|"></div>
147
<!-- Extracted: "hover:bg-blu" -->
148
<!-- Suggestions: filtered to hover:bg-blue-* utilities -->
149
```
150

151
**Multiple Values:**
152
```html
153
<div text="sm white hover:|"></div>
154
<!-- Extracted: "hover:text-" -->
155
<!-- Suggestions: filtered to hover:text-* utilities -->
156
```
157

158
### Special Cases
159

160
The autocomplete handles these special cases:
161

162
**Class Attributes (Ignored):**
163
```html
164
<div class="|"></div>     <!-- No attributify completion -->
165
<div className="|"></div> <!-- No attributify completion -->  
166
<div :class="|"></div>    <!-- No attributify completion -->
167
```
168

169
**Nested HTML in Attributes:**
170
```html
171
<div bg="<span>|</span>"></div>
172
<!-- Recursively processes nested content -->
173
```
174

175
**Variant Completion:**
176
```html
177
<div bg="hov|"></div>
178
<!-- Extracted: "bg-hov" -->
179
<!-- May suggest: hover:bg-* utilities -->
180
```
181

182
### Internal Regex Patterns
183

184
The autocomplete uses these internal regex patterns for parsing:
185

186
```typescript { .api }
187
/**
188
 * Matches HTML elements for autocomplete context detection
189
 * Slightly different pattern from extractor for autocomplete needs
190
 */
191
const elementRE: RegExp;
192

193
/**
194
 * Matches attribute name-value pairs for completion suggestions
195
 * Optimized for interactive cursor-based matching
196
 */
197
const valuedAttributeRE: RegExp;
198

199
/**
200
 * Splits attribute values for multi-value completion
201
 * Handles different quote styles and separators
202
 */
203
const splitterRE: RegExp;
204
```
205

206
### IDE Integration
207

208
The autocomplete integrates with popular development environments:
209

210
**VS Code:**
211
- UnoCSS extension uses this autocomplete
212
- Provides real-time suggestions
213
- Shows utility previews
214

215
**WebStorm/IntelliJ:**
216
- Through UnoCSS plugin
217
- Type-aware completions
218
- Context-sensitive suggestions
219

220
**Other Editors:**
221
- Language Server Protocol (LSP) support
222
- Generic completion through UnoCSS CLI
223

224
### Performance Optimization
225

226
The autocomplete is optimized for performance:
227

228
- **Lazy Evaluation**: Only processes content around cursor
229
- **Caching**: Reuses parsed results when possible
230
- **Efficient Regex**: Optimized patterns for fast matching
231
- **Context Awareness**: Only suggests relevant utilities
232

233
### Error Handling
234

235
The autocomplete gracefully handles:
236

237
- Malformed HTML
238
- Invalid cursor positions
239
- Missing attribute values
240
- Corrupted content
241
- Network timeouts (for remote completions)
242

243
### Configuration Examples
244

245
**Basic Configuration:**
246
```typescript
247
autocompleteExtractorAttributify({
248
  prefix: 'tw-',
249
  prefixedOnly: true
250
})
251
```
252

253
**Framework-Specific:**
254
```typescript
255
// Vue.js setup
256
autocompleteExtractorAttributify({
257
  prefix: 'v-',
258
  trueToNonValued: true
259
})
260

261
// React setup  
262
autocompleteExtractorAttributify({
263
  nonValuedAttribute: false  // JSX doesn't support non-valued attributes
264
})
265
```