0
# Built-in Plugins
1

2
WindiCSS includes several official plugins that extend the framework with specialized utilities for aspect ratios, filters, forms, line clamping, typography, and scroll snap functionality. These plugins demonstrate best practices and provide commonly needed functionality out of the box.
3

4
## Capabilities
5

6
### Aspect Ratio Plugin
7

8
Provides utilities for maintaining aspect ratios of elements, useful for responsive images, videos, and containers.
9

10
```typescript { .api }
11
import aspectRatio from "windicss/plugin/aspect-ratio";
12

13
/**
14
 * Aspect Ratio plugin configuration options
15
 */
16
interface AspectRatioOptions {
17
  /** Custom aspect ratio values */
18
  ratios?: Record<string, string>;
19
  /** Whether to include default ratios */
20
  includeDefaults?: boolean;
21
}
22
```
23

24
**Usage Examples:**
25

26
```typescript
27
import Processor from "windicss";
28
import aspectRatio from "windicss/plugin/aspect-ratio";
29

30
// Basic usage
31
const processor = new Processor({
32
  plugins: [
33
    aspectRatio
34
  ]
35
});
36

37
// With custom ratios
38
const processorCustom = new Processor({
39
  plugins: [
40
    aspectRatio({
41
      ratios: {
42
        'golden': '1.618/1',
43
        'cinema': '2.39/1',
44
        'photo': '4/3'
45
      }
46
    })
47
  ]
48
});
49

50
// Generated utilities:
51
// aspect-square (1:1)
52
// aspect-video (16:9)
53
// aspect-golden (1.618:1)
54
// aspect-cinema (2.39:1)
55
// aspect-photo (4:3)
56
```
57

58
**HTML Examples:**
59

60
```html
61
<!-- Square aspect ratio -->
62
<div class="aspect-square bg-gray-200">
63
  <img src="image.jpg" class="w-full h-full object-cover" alt="Square image">
64
</div>
65

66
<!-- Video aspect ratio -->
67
<div class="aspect-video bg-black">
68
  <iframe src="video.mp4" class="w-full h-full"></iframe>
69
</div>
70

71
<!-- Custom aspect ratio -->
72
<div class="aspect-golden">
73
  <div class="w-full h-full flex items-center justify-center bg-blue-500 text-white">
74
    Golden Ratio Container
75
  </div>
76
</div>
77
```
78

79
### Filters Plugin
80

81
Adds utilities for CSS filter and backdrop-filter effects including blur, brightness, contrast, and more.
82

83
```typescript { .api }
84
import filters from "windicss/plugin/filters";
85

86
/**
87
 * Filters plugin - no configuration options
88
 * Adds comprehensive filter and backdrop-filter utilities
89
 */
90
```
91

92
**Usage Examples:**
93

94
```typescript
95
import Processor from "windicss";
96
import filters from "windicss/plugin/filters";
97

98
const processor = new Processor({
99
  plugins: [
100
    filters
101
  ]
102
});
103

104
// Generated filter utilities:
105
// blur-{size} - Apply blur filter
106
// brightness-{amount} - Adjust brightness
107
// contrast-{amount} - Adjust contrast  
108
// grayscale - Convert to grayscale
109
// hue-rotate-{degrees} - Rotate hue
110
// invert - Invert colors
111
// saturate-{amount} - Adjust saturation
112
// sepia - Apply sepia effect
113

114
// Generated backdrop-filter utilities:
115
// backdrop-blur-{size} - Backdrop blur
116
// backdrop-brightness-{amount} - Backdrop brightness
117
// backdrop-contrast-{amount} - Backdrop contrast
118
// backdrop-grayscale - Backdrop grayscale
119
// backdrop-hue-rotate-{degrees} - Backdrop hue rotation
120
// backdrop-invert - Backdrop invert
121
// backdrop-saturate-{amount} - Backdrop saturation
122
// backdrop-sepia - Backdrop sepia
123
```
124

125
**HTML Examples:**
126

127
```html
128
<!-- Image filters -->
129
<img src="photo.jpg" class="blur-sm brightness-110 contrast-125" alt="Filtered image">
130

131
<!-- Backdrop effects for glass morphism -->
132
<div class="backdrop-blur-md backdrop-brightness-110 bg-white/20 rounded-lg p-6">
133
  <h3 class="text-gray-900 font-semibold">Glass Card</h3>
134
  <p class="text-gray-700">Content with backdrop blur effect</p>
135
</div>
136

137
<!-- Creative filter combinations -->
138
<div class="hover:grayscale-0 grayscale transition-all duration-300">
139
  <img src="artwork.jpg" alt="Artwork with hover effect">
140
</div>
141

142
<!-- Sepia photo effect -->
143
<div class="sepia-75 contrast-125 brightness-105">
144
  <img src="vintage.jpg" class="w-full h-auto" alt="Vintage style photo">
145
</div>
146
```
147

148
### Forms Plugin
149

150
Provides base styles and utilities for form elements with consistent styling across browsers.
151

152
```typescript { .api }
153
import forms from "windicss/plugin/forms";
154

155
/**
156
 * Forms plugin configuration options
157
 */
158
interface FormsOptions {
159
  /** CSS layer for form styles */
160
  layer?: 'base' | 'components';
161
  /** Whether to include default form styles */
162
  includeDefaults?: boolean;
163
}
164
```
165

166
**Usage Examples:**
167

168
```typescript
169
import Processor from "windicss";
170
import forms from "windicss/plugin/forms";
171

172
// Basic usage
173
const processor = new Processor({
174
  plugins: [
175
    forms
176
  ]
177
});
178

179
// With custom configuration
180
const processorCustom = new Processor({
181
  plugins: [
182
    forms({
183
      layer: 'components',
184
      includeDefaults: false
185
    })
186
  ]
187
});
188

189
// Provides normalized styles for:
190
// - Input fields (text, email, password, number, etc.)
191
// - Select dropdowns
192
// - Textareas
193
// - Checkboxes and radio buttons
194
// - File inputs
195
// - Form labels and fieldsets
196
```
197

198
**HTML Examples:**
199

200
```html
201
<!-- Styled form with forms plugin -->
202
<form class="space-y-4">
203
  <!-- Text input with enhanced styling -->
204
  <div>
205
    <label class="block text-sm font-medium text-gray-700">Email</label>
206
    <input 
207
      type="email" 
208
      class="mt-1 block w-full rounded-md border-gray-300 shadow-sm focus:border-blue-500 focus:ring-blue-500"
209
      placeholder="you@example.com"
210
    >
211
  </div>
212

213
  <!-- Select dropdown -->
214
  <div>
215
    <label class="block text-sm font-medium text-gray-700">Country</label>
216
    <select class="mt-1 block w-full rounded-md border-gray-300 shadow-sm focus:border-blue-500 focus:ring-blue-500">
217
      <option>United States</option>
218
      <option>Canada</option>
219
      <option>Mexico</option>
220
    </select>
221
  </div>
222

223
  <!-- Checkbox with custom styling -->
224
  <div class="flex items-center">
225
    <input 
226
      type="checkbox" 
227
      class="h-4 w-4 text-blue-600 focus:ring-blue-500 border-gray-300 rounded"
228
    >
229
    <label class="ml-2 block text-sm text-gray-900">
230
      I agree to the terms and conditions
231
    </label>
232
  </div>
233

234
  <!-- Textarea -->
235
  <div>
236
    <label class="block text-sm font-medium text-gray-700">Message</label>
237
    <textarea 
238
      rows="4" 
239
      class="mt-1 block w-full rounded-md border-gray-300 shadow-sm focus:border-blue-500 focus:ring-blue-500"
240
      placeholder="Your message..."
241
    ></textarea>
242
  </div>
243
</form>
244
```
245

246
### Line Clamp Plugin
247

248
Adds utilities for truncating text to a specific number of lines using CSS line clamping.
249

250
```typescript { .api }
251
import lineClamp from "windicss/plugin/line-clamp";
252

253
/**
254
 * Line Clamp plugin configuration options
255
 */
256
interface LineClampOptions {
257
  /** Custom line counts to generate utilities for */
258
  lines?: number[];
259
  /** Whether to include default line counts */
260
  includeDefaults?: boolean;
261
}
262
```
263

264
**Usage Examples:**
265

266
```typescript
267
import Processor from "windicss";
268
import lineClamp from "windicss/plugin/line-clamp";
269

270
// Basic usage
271
const processor = new Processor({
272
  plugins: [
273
    lineClamp
274
  ]
275
});
276

277
// With custom line counts
278
const processorCustom = new Processor({
279
  plugins: [
280
    lineClamp({
281
      lines: [1, 2, 3, 4, 5, 6, 8, 10],
282
      includeDefaults: true
283
    })
284
  ]
285
});
286

287
// Generated utilities:
288
// line-clamp-1 - Clamp to 1 line
289
// line-clamp-2 - Clamp to 2 lines  
290
// line-clamp-3 - Clamp to 3 lines
291
// line-clamp-none - Remove line clamping
292
```
293

294
**HTML Examples:**
295

296
```html
297
<!-- Single line truncation -->
298
<h3 class="line-clamp-1 text-lg font-semibold">
299
  This is a very long heading that will be truncated to a single line with an ellipsis
300
</h3>
301

302
<!-- Multi-line truncation for descriptions -->
303
<p class="line-clamp-3 text-gray-600 leading-relaxed">
304
  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor 
305
  incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud 
306
  exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute 
307
  irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat.
308
</p>
309

310
<!-- Card with clamped content -->
311
<div class="bg-white rounded-lg shadow-md p-6">
312
  <h4 class="line-clamp-1 text-xl font-bold text-gray-900 mb-2">
313
    Article Title That Might Be Very Long
314
  </h4>
315
  <p class="line-clamp-4 text-gray-600 mb-4">
316
    Article excerpt that provides a preview of the content but is limited to 
317
    exactly four lines to maintain consistent card heights in a grid layout.
318
    This ensures a clean, uniform appearance across multiple cards.
319
  </p>
320
  <button class="text-blue-600 hover:text-blue-800 font-medium">
321
    Read More
322
  </button>
323
</div>
324

325
<!-- Remove line clamping on hover -->
326
<div class="line-clamp-2 hover:line-clamp-none transition-all duration-200">
327
  <p>
328
    Hover over this text to see the full content without line clamping.
329
    This is useful for interactive elements where you want to show more detail on hover.
330
  </p>
331
</div>
332
```
333

334
### Typography Plugin
335

336
Comprehensive typography plugin that provides beautiful default styles for rendered HTML content like blog posts, articles, and documentation.
337

338
```typescript { .api }
339
import typography from "windicss/plugin/typography";
340

341
/**
342
 * Typography plugin configuration options
343
 */
344
interface TypographyOptions {
345
  /** CSS class name for typography styles */
346
  className?: string;
347
  /** Size modifiers to generate */
348
  modifiers?: string[];
349
  /** Whether to include headings styling */
350
  headings?: boolean;
351
  /** Whether to include code styling */
352
  code?: boolean;
353
  /** Whether to include table styling */
354
  tables?: boolean;
355
  /** Custom color themes */
356
  themes?: Record<string, TypographyTheme>;
357
}
358

359
interface TypographyTheme {
360
  colors: {
361
    text: string;
362
    headings: string;
363
    lead: string;
364
    links: string;
365
    bold: string;
366
    counters: string;
367
    bullets: string;
368
    hr: string;
369
    quotes: string;
370
    captions: string;
371
    code: string;
372
    pre: string;
373
  };
374
}
375
```
376

377
**Usage Examples:**
378

379
```typescript
380
import Processor from "windicss";
381
import typography from "windicss/plugin/typography";
382

383
// Basic usage
384
const processor = new Processor({
385
  plugins: [
386
    typography
387
  ]
388
});
389

390
// With full configuration
391
const processorAdvanced = new Processor({
392
  plugins: [
393
    typography({
394
      className: 'prose',
395
      modifiers: ['sm', 'lg', 'xl', '2xl'],
396
      headings: true,
397
      code: true,
398
      tables: true,
399
      themes: {
400
        dark: {
401
          colors: {
402
            text: '#e5e7eb',
403
            headings: '#f9fafb',
404
            lead: '#d1d5db',
405
            links: '#60a5fa',
406
            bold: '#f9fafb',
407
            counters: '#9ca3af',
408
            bullets: '#6b7280',
409
            hr: '#374151',
410
            quotes: '#9ca3af',
411
            captions: '#9ca3af',
412
            code: '#e5e7eb',
413
            pre: '#d1d5db'
414
          }
415
        }
416
      }
417
    })
418
  ]
419
});
420

421
// Generated utilities:
422
// prose - Base typography styles
423
// prose-sm - Small size variant
424
// prose-lg - Large size variant
425
// prose-xl - Extra large variant
426
// prose-2xl - 2X large variant
427
// prose-gray - Gray color theme
428
// prose-blue - Blue color theme
429
// prose-dark - Dark theme
430
```
431

432
**HTML Examples:**
433

434
```html
435
<!-- Basic prose styling -->
436
<article class="prose max-w-none">
437
  <h1>The Future of Web Development</h1>
438
  <p class="lead">
439
    An exploration of emerging technologies and their impact on how we build for the web.
440
  </p>
441
  
442
  <h2>Introduction</h2>
443
  <p>
444
    Web development continues to evolve at a rapid pace. From <strong>framework innovations</strong> 
445
    to new browser APIs, developers have more tools than ever to create amazing experiences.
446
  </p>
447
  
448
  <blockquote>
449
    <p>The best way to predict the future is to invent it.</p>
450
    <cite>Alan Kay</cite>
451
  </blockquote>
452
  
453
  <h3>Key Technologies</h3>
454
  <ul>
455
    <li>Web Components and Custom Elements</li>
456
    <li>Progressive Web Apps (PWAs)</li>
457
    <li>WebAssembly (WASM)</li>
458
    <li>Edge Computing</li>
459
  </ul>
460
  
461
  <pre><code class="language-javascript">
462
// Example of modern JavaScript
463
const fetchData = async (url) => {
464
  try {
465
    const response = await fetch(url);
466
    return await response.json();
467
  } catch (error) {
468
    console.error('Fetch failed:', error);
469
  }
470
};
471
  </code></pre>
472
</article>
473

474
<!-- Different sizes and themes -->
475
<div class="grid grid-cols-1 md:grid-cols-2 gap-8">
476
  <!-- Small prose -->
477
  <article class="prose prose-sm prose-blue">
478
    <h2>Compact Article</h2>
479
    <p>This content uses smaller typography for sidebar or compact layouts.</p>
480
  </article>
481
  
482
  <!-- Large prose with dark theme -->
483
  <article class="prose prose-lg prose-dark bg-gray-900 p-6 rounded-lg">
484
    <h2>Large Dark Article</h2>
485
    <p>This content uses larger typography with a dark color scheme.</p>
486
  </article>
487
</div>
488

489
<!-- Blog post layout -->
490
<main class="max-w-4xl mx-auto px-4 py-8">
491
  <article class="prose prose-lg prose-gray mx-auto">
492
    <header class="mb-8">
493
      <h1>Building Scalable Design Systems</h1>
494
      <p class="lead">
495
        How to create and maintain design systems that grow with your organization.
496
      </p>
497
      <div class="flex items-center space-x-4 text-sm text-gray-500">
498
        <span>By Jane Smith</span>
499
        <span>•</span>
500
        <time datetime="2024-01-15">January 15, 2024</time>
501
        <span>•</span>
502
        <span>8 min read</span>
503
      </div>
504
    </header>
505
    
506
    <!-- Article content automatically styled -->
507
    <h2>Getting Started</h2>
508
    <p>Design systems are more than just UI component libraries...</p>
509
  </article>
510
</main>
511
```
512

513
### Scroll Snap Plugin
514

515
Provides utilities for CSS scroll snap functionality, enabling smooth scrolling experiences and carousel-like behavior.
516

517
```typescript { .api }
518
import scrollSnap from "windicss/plugin/scroll-snap";
519

520
/**
521
 * Scroll Snap plugin - no configuration options
522
 * Adds comprehensive scroll snap utilities
523
 */
524
```
525

526
**Usage Examples:**
527

528
```typescript
529
import Processor from "windicss";
530
import scrollSnap from "windicss/plugin/scroll-snap";
531

532
const processor = new Processor({
533
  plugins: [
534
    scrollSnap
535
  ]
536
});
537

538
// Generated utilities:
539
// snap-none - Disable scroll snap
540
// snap-x - Horizontal scroll snap
541
// snap-y - Vertical scroll snap
542
// snap-both - Both directions
543
// snap-mandatory - Mandatory snapping
544
// snap-proximity - Proximity snapping
545
// snap-start - Snap to start of element
546
// snap-end - Snap to end of element
547
// snap-center - Snap to center of element
548
```
549

550
**HTML Examples:**
551

552
```html
553
<!-- Horizontal scrolling carousel -->
554
<div class="flex overflow-x-auto snap-x snap-mandatory space-x-4 p-4">
555
  <div class="flex-none w-80 h-64 bg-blue-500 rounded-lg snap-start"></div>
556
  <div class="flex-none w-80 h-64 bg-green-500 rounded-lg snap-start"></div>
557
  <div class="flex-none w-80 h-64 bg-purple-500 rounded-lg snap-start"></div>
558
  <div class="flex-none w-80 h-64 bg-red-500 rounded-lg snap-start"></div>
559
</div>
560

561
<!-- Vertical scrolling sections -->
562
<div class="h-screen overflow-y-auto snap-y snap-mandatory">
563
  <section class="h-screen bg-blue-100 snap-start flex items-center justify-center">
564
    <h2 class="text-4xl font-bold">Section 1</h2>
565
  </section>
566
  <section class="h-screen bg-green-100 snap-start flex items-center justify-center">
567
    <h2 class="text-4xl font-bold">Section 2</h2>
568
  </section>
569
  <section class="h-screen bg-purple-100 snap-start flex items-center justify-center">
570
    <h2 class="text-4xl font-bold">Section 3</h2>
571
  </section>
572
</div>
573

574
<!-- Image gallery with center snapping -->
575
<div class="flex overflow-x-auto snap-x snap-mandatory space-x-2 p-4">
576
  <img src="image1.jpg" class="flex-none w-64 h-48 object-cover rounded snap-center" alt="Image 1">
577
  <img src="image2.jpg" class="flex-none w-64 h-48 object-cover rounded snap-center" alt="Image 2">
578
  <img src="image3.jpg" class="flex-none w-64 h-48 object-cover rounded snap-center" alt="Image 3">
579
</div>
580

581
<!-- Card carousel with proximity snapping -->
582
<div class="flex overflow-x-auto snap-x snap-proximity space-x-4 p-4">
583
  <div class="flex-none w-72 bg-white rounded-lg shadow-md p-6 snap-start">
584
    <h3 class="font-semibold mb-2">Card 1</h3>
585
    <p class="text-gray-600">Card content here...</p>
586
  </div>
587
  <div class="flex-none w-72 bg-white rounded-lg shadow-md p-6 snap-start">
588
    <h3 class="font-semibold mb-2">Card 2</h3>
589
    <p class="text-gray-600">Card content here...</p>
590
  </div>
591
</div>
592
```
593

594
### Plugin Usage Best Practices
595

596
Examples of using multiple plugins together effectively.
597

598
```typescript
599
// Comprehensive setup with all plugins
600
import Processor from "windicss";
601
import aspectRatio from "windicss/plugin/aspect-ratio";
602
import filters from "windicss/plugin/filters";
603
import forms from "windicss/plugin/forms";
604
import lineClamp from "windicss/plugin/line-clamp";
605
import typography from "windicss/plugin/typography";
606
import scrollSnap from "windicss/plugin/scroll-snap";
607

608
const processor = new Processor({
609
  plugins: [
610
    aspectRatio,
611
    filters,
612
    forms,
613
    lineClamp({
614
      lines: [1, 2, 3, 4, 5, 6]
615
    }),
616
    typography({
617
      modifiers: ['sm', 'base', 'lg', 'xl'],
618
      themes: {
619
        brand: {
620
          colors: {
621
            text: '#1f2937',
622
            headings: '#111827',
623
            links: '#3b82f6'
624
          }
625
        }
626
      }
627
    }),
628
    scrollSnap
629
  ],
630
  theme: {
631
    extend: {
632
      // Custom theme extensions work with plugins
633
      typography: {
634
        DEFAULT: {
635
          css: {
636
            maxWidth: 'none',
637
            color: '#374151'
638
          }
639
        }
640
      }
641
    }
642
  }
643
});
644

645
// Complex component using multiple plugins
646
const blogPostHTML = `
647
<article class="prose prose-lg prose-brand mx-auto">
648
  <div class="aspect-video mb-6">
649
    <img src="hero.jpg" class="w-full h-full object-cover rounded-lg" alt="Hero">
650
  </div>
651
  
652
  <h1 class="line-clamp-2">Very Long Blog Post Title That Might Wrap</h1>
653
  
654
  <div class="backdrop-blur-sm bg-blue-500/10 p-4 rounded-lg mb-6">
655
    <p class="line-clamp-3 text-blue-800">
656
      This is a highlighted excerpt that provides a preview of the article content.
657
    </p>
658
  </div>
659
  
660
  <div class="flex overflow-x-auto snap-x snap-mandatory space-x-4 my-8">
661
    <div class="flex-none aspect-square w-48 bg-gray-200 rounded-lg snap-start"></div>
662
    <div class="flex-none aspect-square w-48 bg-gray-200 rounded-lg snap-start"></div>
663
    <div class="flex-none aspect-square w-48 bg-gray-200 rounded-lg snap-start"></div>
664
  </div>
665
  
666
  <p>Article content continues with beautiful typography...</p>
667
</article>
668
`;
669
```