0
# Variants System
1

2
Comprehensive variant system providing responsive breakpoints, pseudo-classes, dark mode support, and CSS combinators for conditional styling.
3

4
## Capabilities
5

6
### Variants Function
7

8
Creates variant configurations based on preset options, combining multiple variant categories.
9

10
```typescript { .api }
11
function variants(options: PresetWindOptions): Variant<Theme>[];
12

13
type Variant = (matcher: VariantMatcherContext) => VariantHandlerContext | string | undefined;
14

15
interface VariantMatcherContext {
16
  matcher: string;
17
  generator: UnoGenerator;
18
}
19

20
interface VariantHandlerContext {
21
  matcher: string;
22
  handle?: VariantHandler;
23
  multiPass?: boolean;
24
  sort?: number;
25
  layer?: string;
26
}
27

28
type VariantHandler = (input: VariantHandlerInput, next: VariantHandlerNext) => VariantHandlerReturn;
29
```
30

31
### Variant Categories
32

33
#### Combinator Variants
34

35
CSS combinator variants for selecting related elements.
36

37
```typescript { .api }
38
// From variants/combinators
39
const combinatorVariants: Variant[];
40
```
41

42
**Features:**
43
- Child combinator variants (`>`)
44
- Adjacent sibling variants (`+`)
45
- General sibling variants (`~`)
46
- Descendant selector variants
47

48
#### Dark Mode Variants
49

50
Dark and light mode variants using class-based and media query approaches.
51

52
```typescript { .api }
53
const variantColorsScheme: Variant[];
54
```
55

56
**Class-based Variants:**
57
- `.dark` - Applies styles when `.dark` class is present on parent
58
- `.light` - Applies styles when `.light` class is present on parent
59

60
**Media Query Variants:**
61
- `@dark` - Applies styles when system prefers dark color scheme
62
- `@light` - Applies styles when system prefers light color scheme
63

64
**Usage Examples:**
65

66
```html
67
<!-- Class-based dark mode -->
68
<div class="bg-white dark:bg-gray-900">
69
  <p class="text-black dark:text-white">Content</p>
70
</div>
71

72
<!-- Media query dark mode -->
73
<div class="bg-white @dark:bg-gray-900">
74
  <p class="text-black @dark:text-white">Content</p>
75
</div>
76
```
77

78
#### Default Variants
79

80
Core variant set from preset-mini including responsive breakpoints and pseudo-classes.
81

82
```typescript { .api }
83
// From variants/default  
84
const defaultVariants: Variant[];
85
```
86

87
**Features:**
88
- Responsive breakpoints (`sm:`, `md:`, `lg:`, `xl:`, `2xl:`)
89
- Pseudo-classes (`:hover`, `:focus`, `:active`, etc.)
90
- Pseudo-elements (`::before`, `::after`, `::placeholder`)
91
- State variants (`:checked`, `:disabled`, `:required`)
92

93
#### Media Query Variants
94

95
Extended media query variants for user preferences and device capabilities.
96

97
```typescript { .api }
98
// From variants/media
99
const mediaVariants: Variant[];
100
```
101

102
**Features:**
103
- Orientation variants (`portrait:`, `landscape:`)
104
- Color scheme variants (`os-dark:`, `os-light:`)
105
- Motion preference variants (`motion-ok:`, `motion-not-ok:`)
106
- Contrast preference variants (`high-contrast:`, `low-contrast:`)
107
- Transparency preference variants (`opacity-ok:`, `opacity-not-ok:`)
108
- Data usage variants (`use-data-ok:`, `use-data-not-ok:`)
109
- Input method variants (`touch:`, `stylus:`, `pointer:`, `mouse:`)
110
- Color gamut variants (`hd-color:`)
111

112
#### Miscellaneous Variants
113

114
Additional utility variants for special cases.
115

116
```typescript { .api }
117
// From variants/misc
118
const miscVariants: Variant[];
119
```
120

121
**Features:**
122
- Print media variants
123
- Container query variants
124
- CSS supports variants
125
- Custom selector variants
126

127
#### Placeholder Variants
128

129
Placeholder pseudo-element variants for input styling.
130

131
```typescript { .api }
132
// From variants/placeholder
133
const placeholderVariants: Variant[];
134
```
135

136
**Features:**
137
- `::placeholder` pseudo-element styling
138
- Placeholder-specific color and typography utilities
139

140
### Variant Usage Patterns
141

142
#### Responsive Design
143

144
```html
145
<!-- Responsive utility classes -->
146
<div class="w-full md:w-1/2 lg:w-1/3">
147
  <p class="text-sm sm:text-base lg:text-lg">Responsive text</p>
148
</div>
149
```
150

151
#### Interactive States
152

153
```html
154
<!-- Hover and focus states -->
155
<button class="bg-blue-500 hover:bg-blue-700 focus:ring-2 focus:ring-blue-300">
156
  Click me
157
</button>
158
```
159

160
#### Dark Mode
161

162
```html
163
<!-- Dark mode variants -->
164
<div class="bg-white dark:bg-gray-800">
165
  <h1 class="text-gray-900 dark:text-white">Title</h1>
166
</div>
167
```
168

169
#### User Preferences
170

171
```html
172
<!-- Motion and accessibility -->
173
<div class="animate-pulse motion-not-ok:animate-none">
174
  <p class="text-base high-contrast:text-lg">Accessible content</p>
175
</div>
176
```
177

178
#### Device Capabilities
179

180
```html
181
<!-- Touch and input method variants -->
182
<button class="p-2 touch:p-4 mouse:hover:bg-gray-100">
183
  Adaptive button
184
</button>
185
```
186

187
### Variant Ordering
188

189
Variants are applied in a specific order to ensure proper CSS cascade:
190

191
1. Responsive breakpoints
192
2. User preference media queries  
193
3. Interactive states
194
4. Dark/light mode
195
5. Pseudo-elements
196
6. Combinators
197

198
**Usage Example:**
199

200
```typescript
201
import { variants } from "@unocss/preset-wind";
202

203
// Create variants with options
204
const variantList = variants({
205
  important: false
206
});
207

208
// Variants are used internally by the preset
209
// Individual variant access for advanced use cases
210
```