0
# Configuration & Theming
1

2
WindiCSS configuration system provides comprehensive theming, plugin management, and processor customization. The configuration follows the same principles as Tailwind CSS but with additional WindiCSS-specific features.
3

4
## Capabilities
5

6
### Configuration Interface
7

8
Main configuration object for customizing WindiCSS behavior, theme, and plugins.
9

10
```typescript { .api }
11
interface Config {
12
  /** Theme configuration with colors, spacing, typography, etc. */
13
  theme?: Theme;
14
  /** Array of plugins to load */
15
  plugins?: Plugin[];
16
  /** Preset configurations to extend */
17
  presets?: Config[];
18
  /** Variant configuration per utility */
19
  variants?: Record<string, string[]> | string[];
20
  /** Custom shortcuts for frequently used class combinations */
21
  shortcuts?: Record<string, Shortcut>;
22
  /** Class name aliases for alternative naming */
23
  alias?: Record<string, string>;
24
  /** RegExp patterns to exclude from processing */
25
  exclude?: RegExp[];
26
  /** Make all utilities important, or important within a selector */
27
  important?: boolean | string;
28
  /** Prefix for all generated classes */
29
  prefix?: string;
30
  /** Separator for variants (default: ':') */
31
  separator?: string;
32
  /** Attributify mode configuration */
33
  attributify?: boolean | AttributifyOptions;
34
  /** Preflight/base styles configuration */
35
  preflight?: boolean | PreflightOptions;
36
  /** Core plugins to enable/disable */
37
  corePlugins?: string[] | Record<string, boolean>;
38
  /** Utility handlers for custom processing */
39
  handlers?: Record<string, any>;
40
}
41
```
42

43
### Theme Configuration
44

45
Theme system for colors, spacing, typography, and other design tokens.
46

47
```typescript { .api }
48
interface Theme {
49
  /** Extend the default theme */
50
  extend?: Record<string, any>;
51
  /** Color palette */
52
  colors?: Record<string, string | Record<string, string>>;
53
  /** Spacing scale */
54
  spacing?: Record<string, string>;
55
  /** Screen breakpoints */
56
  screens?: Record<string, string>;
57
  /** Font families */
58
  fontFamily?: Record<string, string | string[]>;
59
  /** Font sizes */
60
  fontSize?: Record<string, FontSize>;
61
  /** Font weights */
62
  fontWeight?: Record<string, string>;
63
  /** Line heights */
64
  lineHeight?: Record<string, string>;
65
  /** Letter spacing */
66
  letterSpacing?: Record<string, string>;
67
  /** Border radius */
68
  borderRadius?: Record<string, string>;
69
  /** Border widths */
70
  borderWidth?: Record<string, string>;
71
  /** Box shadows */
72
  boxShadow?: Record<string, string>;
73
  /** Z-index values */
74
  zIndex?: Record<string, string>;
75
  /** Opacity values */
76
  opacity?: Record<string, string>;
77
  /** Animation configurations */
78
  animation?: Record<string, string>;
79
  /** Keyframe definitions */
80
  keyframes?: Record<string, Record<string, Record<string, string>>>;
81
  /** CSS variables */
82
  vars?: Record<string, string>;
83
  [key: string]: any;
84
}
85

86
type FontSize =
87
  | string
88
  | [fontSize: string, letterSpacing?: string]
89
  | [fontSize?: string, options?: { letterSpacing?: string; lineHeight?: string }];
90
```
91

92
**Usage Examples:**
93

94
```typescript
95
import Processor from "windicss";
96

97
// Basic theme extension
98
const processor = new Processor({
99
  theme: {
100
    extend: {
101
      colors: {
102
        primary: {
103
          50: '#eff6ff',
104
          500: '#3b82f6',
105
          900: '#1e3a8a'
106
        },
107
        secondary: '#10b981'
108
      },
109
      spacing: {
110
        '18': '4.5rem',
111
        '88': '22rem'
112
      },
113
      fontFamily: {
114
        'custom': ['Inter', 'system-ui', 'sans-serif']
115
      }
116
    }
117
  }
118
});
119

120
// Complete theme override
121
const customTheme = {
122
  colors: {
123
    // Custom color system
124
    gray: {
125
      100: '#f5f5f5',
126
      500: '#737373',
127
      900: '#171717'
128
    }
129
  },
130
  spacing: {
131
    // Custom spacing scale
132
    'xs': '0.5rem',
133
    'sm': '1rem',
134
    'md': '1.5rem',
135
    'lg': '2rem'
136
  }
137
};
138
```
139

140
### Plugin Configuration
141

142
Plugin system for extending WindiCSS with custom utilities, components, and variants.
143

144
```typescript { .api }
145
type Plugin = PluginOutput | PluginWithOptions<any>;
146

147
interface PluginOutput {
148
  handler: PluginHandler;
149
  config?: Config;
150
}
151

152
interface PluginWithOptions<T> {
153
  (options?: T): PluginOutput;
154
  __isOptionsFunction: true;
155
  __pluginFunction: (options: T) => PluginHandler;
156
  __configFunction: (options: T) => Config;
157
}
158

159
type PluginHandler = (utils: PluginUtils) => void;
160
```
161

162
**Usage Examples:**
163

164
```typescript
165
import Processor from "windicss";
166
import plugin from "windicss/plugin";
167
import typography from "windicss/plugin/typography";
168

169
const processor = new Processor({
170
  plugins: [
171
    // Built-in plugin
172
    typography,
173
    
174
    // Custom plugin without options
175
    plugin(({ addUtilities }) => {
176
      addUtilities({
177
        '.btn': {
178
          padding: '0.5rem 1rem',
179
          borderRadius: '0.375rem',
180
          fontWeight: '500'
181
        }
182
      });
183
    }),
184
    
185
    // Custom plugin with configuration
186
    plugin(({ addBase, theme }) => {
187
      addBase({
188
        'body': {
189
          color: theme('colors.gray.900'),
190
          backgroundColor: theme('colors.gray.50')
191
        }
192
      });
193
    }, {
194
      theme: {
195
        extend: {
196
          colors: {
197
            brand: '#ff6b6b'
198
          }
199
        }
200
      }
201
    })
202
  ]
203
});
204
```
205

206
### Shortcuts Configuration
207

208
Shortcuts allow defining reusable class combinations with custom names.
209

210
```typescript { .api }
211
type Shortcut = string | Record<string, any>;
212
```
213

214
**Usage Examples:**
215

216
```typescript
217
const processor = new Processor({
218
  shortcuts: {
219
    // String-based shortcuts
220
    'btn': 'px-4 py-2 rounded-lg font-medium transition-colors',
221
    'btn-primary': 'btn bg-blue-500 text-white hover:bg-blue-600',
222
    'card': 'bg-white shadow-lg rounded-xl p-6',
223
    
224
    // Object-based shortcuts with CSS properties
225
    'flex-center': {
226
      display: 'flex',
227
      alignItems: 'center',
228
      justifyContent: 'center'
229
    },
230
    'text-gradient': {
231
      background: 'linear-gradient(45deg, #3b82f6, #10b981)',
232
      WebkitBackgroundClip: 'text',
233
      WebkitTextFillColor: 'transparent'
234
    }
235
  }
236
});
237

238
// Usage in HTML
239
// <button class="btn-primary">Click me</button>
240
// <div class="card flex-center">Content</div>
241
```
242

243
### Alias Configuration
244

245
Class name aliases provide alternative names for existing utilities.
246

247
```typescript { .api }
248
interface AliasConfig {
249
  [aliasName: string]: string;
250
}
251
```
252

253
**Usage Example:**
254

255
```typescript
256
const processor = new Processor({
257
  alias: {
258
    // Alternative naming
259
    'hstack': 'flex items-center',
260
    'vstack': 'flex flex-col',
261
    'center': 'flex items-center justify-center',
262
    
263
    // Shortened names
264
    'bg-primary': 'bg-blue-500',
265
    'text-muted': 'text-gray-600'
266
  }
267
});
268
```
269

270
### Attributify Configuration
271

272
Configuration for attributify mode, allowing utility classes as HTML attributes.
273

274
```typescript { .api }
275
interface AttributifyOptions {
276
  /** Prefix for attributify attributes */
277
  prefix?: string;
278
  /** Separator for variant and utility (default: ':') */
279
  separator?: string;
280
  /** Array of attributes to disable */
281
  disable?: string[];
282
}
283
```
284

285
**Usage Examples:**
286

287
```typescript
288
// Enable attributify mode
289
const processor = new Processor({
290
  attributify: true
291
});
292

293
// Attributify with custom options
294
const processorWithOptions = new Processor({
295
  attributify: {
296
    prefix: 'w-',
297
    separator: '-',
298
    disable: ['container']
299
  }
300
});
301

302
// HTML examples:
303
// <div bg="blue-500" text="white" p="4">Basic attributify</div>
304
// <div w-bg="red-500" w-text="white">With prefix</div>
305
// <div bg="hover-blue-600">With variants</div>
306
```
307

308
### Preflight Configuration
309

310
Configuration for CSS reset and base styles.
311

312
```typescript { .api }
313
interface PreflightOptions {
314
  /** Classes to always include in preflight */
315
  safelist?: string | string[];
316
  /** Classes to exclude from preflight */
317
  blocklist?: string | string[];
318
  /** Tag name aliases for preflight */
319
  alias?: Record<string, string>;
320
  /** Enable all preflight features */
321
  enableAll?: boolean;
322
}
323
```
324

325
**Usage Example:**
326

327
```typescript
328
const processor = new Processor({
329
  preflight: {
330
    safelist: ['container', 'btn', 'card'],
331
    blocklist: ['debug-*'],
332
    alias: {
333
      'hstack': 'div',
334
      'vstack': 'div'
335
    },
336
    enableAll: false
337
  }
338
});
339
```
340

341
### Variant Configuration
342

343
Configuration for responsive, state, and custom variants.
344

345
```typescript { .api }
346
type VariantConfig = Record<string, string[]> | string[];
347
```
348

349
**Usage Examples:**
350

351
```typescript
352
// Global variants (apply to all utilities)
353
const processor = new Processor({
354
  variants: ['responsive', 'hover', 'focus', 'dark']
355
});
356

357
// Per-utility variants
358
const processorPerUtility = new Processor({
359
  variants: {
360
    backgroundColor: ['responsive', 'hover', 'focus', 'dark'],
361
    textColor: ['responsive', 'hover', 'focus'],
362
    borderWidth: ['responsive']
363
  }
364
});
365
```
366

367
### Core Plugins Configuration
368

369
Enable or disable built-in WindiCSS utilities.
370

371
```typescript { .api }
372
type CorePluginsConfig = string[] | Record<string, boolean>;
373
```
374

375
**Usage Examples:**
376

377
```typescript
378
// Array format - only enable specific plugins
379
const processor = new Processor({
380
  corePlugins: [
381
    'margin',
382
    'padding', 
383
    'backgroundColor',
384
    'textColor'
385
  ]
386
});
387

388
// Object format - fine-grained control
389
const processorObject = new Processor({
390
  corePlugins: {
391
    // Enable
392
    margin: true,
393
    padding: true,
394
    backgroundColor: true,
395
    
396
    // Disable
397
    float: false,
398
    clear: false,
399
    skew: false
400
  }
401
});
402
```
403

404
### Default Configurations
405

406
Access to built-in default configurations.
407

408
```typescript { .api }
409
/**
410
 * Default WindiCSS configuration
411
 */
412
declare const defaultConfig: Config;
413

414
/**
415
 * Default WindiCSS theme
416
 */
417
declare const defaultTheme: Theme;
418

419
/**
420
 * Default color palette
421
 */
422
declare const colors: Record<string, string | Record<string, string>>;
423
```
424

425
**Usage Example:**
426

427
```typescript
428
import { defaultConfig, defaultTheme, colors } from "windicss";
429

430
// Extend default configuration
431
const processor = new Processor({
432
  ...defaultConfig,
433
  theme: {
434
    ...defaultTheme,
435
    extend: {
436
      colors: {
437
        ...colors,
438
        brand: '#ff6b6b'
439
      }
440
    }
441
  }
442
});
443
```
444

445
### Configuration Utilities
446

447
Helper functions for working with configurations.
448

449
```typescript { .api }
450
/**
451
 * Type-safe configuration definition helper
452
 * @param config - Configuration object
453
 * @returns Same configuration with type safety
454
 */
455
function defineConfig(config: Config): Config;
456
```
457

458
**Usage Example:**
459

460
```typescript
461
import { defineConfig } from "windicss/helpers";
462

463
export default defineConfig({
464
  theme: {
465
    extend: {
466
      colors: {
467
        primary: '#3b82f6'
468
      }
469
    }
470
  },
471
  plugins: [
472
    // plugins here
473
  ]
474
});
475
```