0
# TypeScript Definitions
1

2
Type-safe attribute names and values for TypeScript and JSX usage, providing full IntelliSense support and compile-time validation for attributify syntax.
3

4
## Capabilities
5

6
### Attributify Names
7

8
Generic type for generating type-safe attribute names with optional prefixes.
9

10
```typescript { .api }
11
/**
12
 * Type-safe attribute names for attributify usage
13
 * @template Prefix - Optional prefix string for attribute names
14
 */
15
type AttributifyNames<Prefix extends string = ''> = 
16
  | `${Prefix}${BasicAttributes}`
17
  | `${Prefix}${PseudoPrefix}:${BasicAttributes}`;
18
```
19

20
### Attributify Attributes Interface
21

22
Main interface for type-safe attributify attributes in JSX/TSX.
23

24
```typescript { .api }
25
/**
26
 * Interface providing type-safe attribute names for JSX/TSX usage
27
 * Extends Partial<Record> to make all attributes optional
28
 */
29
interface AttributifyAttributes extends Partial<Record<AttributifyNames, string | boolean>> {}
30
```
31

32
**Usage Examples:**
33

34
```tsx
35
import type { AttributifyAttributes } from '@unocss/preset-attributify'
36

37
// Use in React component props
38
interface ButtonProps extends AttributifyAttributes {
39
  children: React.ReactNode;
40
}
41

42
function Button(props: ButtonProps) {
43
  return <button {...props} />;
44
}
45

46
// Usage with full type safety
47
<Button 
48
  bg="blue-500 hover:blue-600"    // ✓ Valid
49
  text="white sm"                 // ✓ Valid  
50
  p="x-4 y-2"                     // ✓ Valid
51
  invalidAttr="value"             // ✗ TypeScript error
52
/>
53
```
54

55
### Basic Attributes
56

57
Union of all basic utility attribute types.
58

59
```typescript { .api }
60
/**
61
 * All basic attribute types available in attributify mode
62
 */
63
type BasicAttributes = SpecialSingleWord | TwoStringsComposition | SeparateEnabled;
64
```
65

66
### Special Single Word Utilities
67

68
Utilities that work as complete UnoCSS rules by themselves.
69

70
```typescript { .api }
71
/**
72
 * Complete UnoCSS utilities that work as single words
73
 */
74
type SpecialSingleWord = 
75
  | 'container'
76
  | 'flex' 
77
  | 'block'
78
  | 'inline'
79
  | 'table'
80
  | 'isolate'
81
  | 'absolute'
82
  | 'relative'
83
  | 'fixed'
84
  | 'sticky'
85
  | 'static'
86
  | 'visible'
87
  | 'invisible'
88
  | 'grow'
89
  | 'shrink'
90
  | 'antialiased'
91
  | 'italic'
92
  | 'ordinal'
93
  | 'overline'
94
  | 'underline'
95
  | 'uppercase'
96
  | 'lowercase'
97
  | 'capitalize'
98
  | 'truncate'
99
  | 'border'
100
  | 'rounded'
101
  | 'outline'
102
  | 'ring'
103
  | 'shadow'
104
  | 'blur'
105
  | 'grayscale'
106
  | 'invert'
107
  | 'sepia'
108
  | 'transition'
109
  | 'resize'
110
  | 'transform'
111
  | 'filter';
112
```
113

114
### Two Strings Composition
115

116
Utilities that combine two characters to form complete utilities.
117

118
```typescript { .api }
119
/**
120
 * Valid prefixes for two-string composition utilities
121
 */
122
type TwoStringsCompositionPrefix = 'm' | 'p';
123

124
/**
125
 * Valid suffixes for two-string composition utilities  
126
 */
127
type TwoStringsCompositionSuffix = 'r' | 'b' | 'l' | 't' | 'a' | 'x' | 'y';
128

129
/**
130
 * Two-character utility combinations plus special cases
131
 */
132
type TwoStringsComposition = 
133
  | `${TwoStringsCompositionPrefix}${TwoStringsCompositionSuffix}`
134
  | 'ha' 
135
  | 'wa';
136
```
137

138
**Examples:**
139
- `mr` → `margin-right`
140
- `pt` → `padding-top` 
141
- `ha` → `height-auto`
142
- `wa` → `width-auto`
143

144
### Pseudo Prefixes
145

146
Valid pseudo-class and breakpoint prefixes for variants.
147

148
```typescript { .api }
149
/**
150
 * Valid pseudo-class and breakpoint prefixes
151
 */
152
type PseudoPrefix = 
153
  | 'active'
154
  | 'before'
155
  | 'after'
156
  | 'dark'
157
  | 'light'
158
  | 'first'
159
  | 'last'
160
  | 'focus'
161
  | 'hover'
162
  | 'link'
163
  | 'root'
164
  | 'sm'
165
  | 'md'
166
  | 'lg'
167
  | 'xl'
168
  | '2xl'
169
  | 'enabled'
170
  | 'disabled'
171
  | 'all'
172
  | 'children';
173
```
174

175
### Separate Enabled Utilities
176

177
Utilities that can contain multiple space-separated values.
178

179
```typescript { .api }
180
/**
181
 * Utilities that can separate multiple values with spaces
182
 * For example: font="mono light", text="sm white"
183
 */
184
type SeparateEnabled = 
185
  | 'align'
186
  | 'animate'
187
  | 'backdrop'
188
  | 'bg'
189
  | 'blend'
190
  | 'border'
191
  | 'box'
192
  | 'container'
193
  | 'content'
194
  | 'cursor'
195
  | 'display'
196
  | 'divide'
197
  | 'filter'
198
  | 'flex'
199
  | 'font'
200
  | 'fw'
201
  | 'gap'
202
  | 'gradient'
203
  | 'grid'
204
  | 'h'
205
  | 'icon'
206
  | 'items'
207
  | 'justify'
208
  | 'list'
209
  | 'm'
210
  | 'op'
211
  | 'opacity'
212
  | 'order'
213
  | 'outline'
214
  | 'overflow'
215
  | 'p'
216
  | 'place'
217
  | 'pos'
218
  | 'position'
219
  | 'ring'
220
  | 'select'
221
  | 'shadow'
222
  | 'size'
223
  | 'space'
224
  | 'table'
225
  | 'text'
226
  | 'transform'
227
  | 'transition'
228
  | 'underline'
229
  | 'w'
230
  | 'z'
231
  | PseudoPrefix;
232
```
233

234
### Usage Patterns
235

236
**React/JSX Usage:**
237

238
```tsx
239
import type { AttributifyAttributes } from '@unocss/preset-attributify'
240

241
// Extend component props
242
interface CardProps extends AttributifyAttributes {
243
  title: string;
244
  children: React.ReactNode;
245
}
246

247
function Card({ title, children, ...attrs }: CardProps) {
248
  return (
249
    <div 
250
      bg="white dark:gray-800"
251
      border="rounded-lg"
252
      p="6"
253
      shadow="lg"
254
      {...attrs}
255
    >
256
      <h2 text="xl font-bold">{title}</h2>
257
      {children}
258
    </div>
259
  );
260
}
261
```
262

263
**Vue.js Usage:**
264

265
```vue
266
<script setup lang="ts">
267
import type { AttributifyAttributes } from '@unocss/preset-attributify'
268

269
interface Props extends AttributifyAttributes {
270
  title: string;
271
}
272

273
defineProps<Props>();
274
</script>
275

276
<template>
277
  <div 
278
    bg="white dark:gray-800"
279
    border="rounded-lg" 
280
    p="6"
281
    shadow="lg"
282
  >
283
    <h2 text="xl font-bold">{{ title }}</h2>
284
    <slot />
285
  </div>
286
</template>
287
```
288

289
**Custom Prefix Support:**
290

291
```typescript
292
import type { AttributifyNames } from '@unocss/preset-attributify'
293

294
// Custom prefix type
295
type UIAttributes = Partial<Record<AttributifyNames<'ui-'>, string | boolean>>;
296

297
interface ComponentProps extends UIAttributes {
298
  // Component-specific props
299
}
300

301
// Usage
302
<div 
303
  ui-bg="blue-500"
304
  ui-text="white"
305
  ui-p="4"
306
/>
307
```
308

309
### Type Augmentation
310

311
For global type augmentation in JSX environments:
312

313
```typescript
314
// types/jsx.d.ts
315
import type { AttributifyAttributes } from '@unocss/preset-attributify'
316

317
declare module 'react' {
318
  interface HTMLAttributes<T> extends AttributifyAttributes {}
319
}
320

321
// Now all HTML elements support attributify
322
<div bg="blue-500" text="white" />  // ✓ Type-safe everywhere
323
```
324

325
### Framework-Specific Types
326

327
**React:**
328
```typescript
329
import type { HTMLAttributes } from 'react'
330
import type { AttributifyAttributes } from '@unocss/preset-attributify'
331

332
type ReactAttributifyProps<T = HTMLElement> = HTMLAttributes<T> & AttributifyAttributes;
333
```
334

335
**Vue:**
336
```typescript
337
import type { AllowedComponentProps } from 'vue'
338
import type { AttributifyAttributes } from '@unocss/preset-attributify'
339

340
type VueAttributifyProps = AllowedComponentProps & AttributifyAttributes;
341
```
342

343
### Limitations and Notes
344

345
**Boolean Attributes:**
346
```tsx
347
// Both string and boolean values are supported
348
<div block />           // boolean: true
349
<div block="true" />    // string: "true"  
350
<div block={true} />    // boolean: true (JSX)
351
```
352

353
**Complex Values:**
354
```tsx
355
// String values support complex utilities
356
<div bg="gradient-to-r from-blue-500 to-purple-600" />
357
<div text="lg font-bold leading-tight" />
358
```
359

360
**Type Checking:**
361
- Provides IntelliSense for attribute names
362
- Validates attribute names at compile time
363
- Does not validate attribute values (UnoCSS handles this at runtime)
364
- Works with all TypeScript-enabled editors