0
# Variants
1

2
Comprehensive variant system supporting responsive breakpoints, pseudo-classes, dark mode, arbitrary selectors, and advanced CSS targeting for conditional utility application.
3

4
## Capabilities
5

6
### Variants Function
7

8
Creates the complete collection of variant handlers for the preset.
9

10
```typescript { .api }
11
/**
12
 * Creates variants collection with configuration-based customization
13
 * @param options - Preset configuration options affecting variant behavior
14
 * @returns Array of variant handlers for the preset
15
 */
16
function variants(options: PresetMiniOptions): Variant[];
17
```
18

19
**Usage Example:**
20

21
```typescript
22
import { variants } from "@unocss/preset-mini/variants";
23
import type { PresetMiniOptions } from "@unocss/preset-mini";
24

25
const options: PresetMiniOptions = {
26
  dark: 'class',
27
  attributifyPseudo: false,
28
};
29

30
const variantHandlers = variants(options);
31
```
32

33
## Variant Categories
34

35
### Responsive Breakpoints
36

37
Responsive design variants using mobile-first approach with theme-defined breakpoints.
38

39
**Breakpoint Variants:**
40
- `sm:` - `@media (min-width: 640px)`
41
- `md:` - `@media (min-width: 768px)`
42
- `lg:` - `@media (min-width: 1024px)`
43
- `xl:` - `@media (min-width: 1280px)`
44
- `2xl:` - `@media (min-width: 1536px)`
45

46
**Custom range variants:**
47
- `<sm:` - `@media (max-width: 639px)`
48
- `<md:` - `@media (max-width: 767px)`
49
- `@md:` - `@media (min-width: 768px) and (max-width: 1023px)`
50

51
**Vertical breakpoint variants (height-based):**
52
- Available when `verticalBreakpoints` are defined in theme
53

54
**Usage Examples:**
55

56
```html
57
<!-- Responsive width -->
58
<div class="w-full md:w-1/2 lg:w-1/3">
59
  Responsive width
60
</div>
61

62
<!-- Responsive text size -->
63
<h1 class="text-xl md:text-2xl lg:text-3xl">
64
  Responsive heading
65
</h1>
66
```
67

68
### Dark Mode Variants
69

70
Dark mode support with configurable detection method.
71

72
**Dark Mode Variants:**
73
- `dark:` - Applied in dark mode context
74
- `light:` - Applied in light mode context (when using custom selectors)
75

76
**Configuration-dependent behavior:**
77

78
```typescript
79
// Class-based (default)
80
dark: 'class' // Uses .dark ancestor selector
81

82
// Media query-based
83
dark: 'media' // Uses @media (prefers-color-scheme: dark)
84

85
// Custom selectors
86
dark: {
87
  dark: '.dark-theme',
88
  light: '.light-theme'
89
}
90
```
91

92
**Usage Examples:**
93

94
```html
95
<!-- Class-based dark mode -->
96
<div class="bg-white dark:bg-gray-900 text-black dark:text-white">
97
  Content with dark mode
98
</div>
99

100
<!-- Works with any utility -->
101
<button class="border border-gray-300 dark:border-gray-700 hover:bg-gray-100 dark:hover:bg-gray-800">
102
  Button with dark mode
103
</button>
104
```
105

106
### Pseudo-Class Variants
107

108
Comprehensive pseudo-class support for interactive states and element targeting.
109

110
**Interactive States:**
111
- `hover:` - `:hover`
112
- `focus:` - `:focus`
113
- `active:` - `:active`
114
- `visited:` - `:visited`
115
- `focus-within:` - `:focus-within`
116
- `focus-visible:` - `:focus-visible`
117

118
**Form States:**
119
- `checked:` - `:checked`
120
- `disabled:` - `:disabled`
121
- `enabled:` - `:enabled`
122
- `required:` - `:required`
123
- `invalid:` - `:invalid`
124
- `valid:` - `:valid`
125
- `in-range:` - `:in-range`
126
- `out-of-range:` - `:out-of-range`
127

128
**Structural Pseudo-classes:**
129
- `first:` - `:first-child`
130
- `last:` - `:last-child`
131
- `odd:` - `:nth-child(odd)`
132
- `even:` - `:nth-child(even)`
133
- `first-of-type:` - `:first-of-type`
134
- `last-of-type:` - `:last-of-type`
135
- `only:` - `:only-child`
136
- `only-of-type:` - `:only-of-type`
137

138
**Usage Examples:**
139

140
```html
141
<!-- Interactive states -->
142
<button class="bg-blue-500 hover:bg-blue-600 focus:ring-2 focus:ring-blue-300 active:bg-blue-700">
143
  Interactive button
144
</button>
145

146
<!-- Form validation states -->
147
<input class="border border-gray-300 valid:border-green-500 invalid:border-red-500" />
148

149
<!-- Structural targeting -->
150
<ul>
151
  <li class="first:font-bold odd:bg-gray-100">Item 1</li>
152
  <li class="odd:bg-gray-100">Item 2</li>
153
  <li class="last:border-b-0 odd:bg-gray-100">Item 3</li>
154
</ul>
155
```
156

157
### Pseudo-Element Variants
158

159
Pseudo-element variants for content generation and styling.
160

161
**Available Pseudo-elements:**
162
- `before:` - `::before`
163
- `after:` - `::after` 
164
- `first-line:` - `::first-line`
165
- `first-letter:` - `::first-letter`
166
- `backdrop:` - `::backdrop`
167
- `placeholder:` - `::placeholder`
168
- `file:` - `::file-selector-button`
169
- `marker:` - `::marker`
170
- `selection:` - `::selection`
171

172
**Usage Examples:**
173

174
```html
175
<!-- Decorative elements -->
176
<div class="before:content-[''] before:absolute before:inset-0 before:bg-gradient-to-r before:from-blue-500 before:to-purple-500">
177
  Content with gradient overlay
178
</div>
179

180
<!-- Form styling -->
181
<input class="placeholder:text-gray-400 placeholder:italic" placeholder="Enter text..." />
182
```
183

184
### ARIA and Data Attribute Variants
185

186
Support for ARIA states and custom data attributes.
187

188
**ARIA Variants:**
189
- `aria-checked:` - `[aria-checked="true"]`
190
- `aria-disabled:` - `[aria-disabled="true"]`
191
- `aria-expanded:` - `[aria-expanded="true"]`
192
- `aria-hidden:` - `[aria-hidden="true"]`
193
- `aria-pressed:` - `[aria-pressed="true"]`
194
- `aria-readonly:` - `[aria-readonly="true"]`
195
- `aria-required:` - `[aria-required="true"]`
196
- `aria-selected:` - `[aria-selected="true"]`
197

198
**Data Attribute Variants:**
199
- `data-*:` - Custom data attribute matching
200
- Configurable through theme `data` configuration
201

202
**Usage Examples:**
203

204
```html
205
<!-- ARIA-based styling -->
206
<button class="aria-expanded:bg-blue-100 aria-pressed:bg-blue-200" aria-expanded="false">
207
  Expandable button
208
</button>
209

210
<!-- Data attribute styling -->
211
<div class="data-[state=open]:bg-green-100" data-state="closed">
212
  State-dependent styling
213
</div>
214
```
215

216
### Child and Sibling Combinators
217

218
Advanced selector combinators for targeting related elements.
219

220
**Child Combinators:**
221
- `*:` - `> *` (direct children)
222
- `first-child:` - `> :first-child`
223
- `last-child:` - `> :last-child`
224

225
**Group Variants:**
226
- `group-hover:` - Applied when ancestor with `group` class is hovered
227
- `group-focus:` - Applied when ancestor with `group` class is focused
228
- `group-active:` - Applied when ancestor with `group` class is active
229

230
**Usage Examples:**
231

232
```html
233
<!-- Group interaction -->
234
<div class="group">
235
  <img class="group-hover:scale-110 transition-transform" />
236
  <p class="group-hover:text-blue-600">Hover the parent to transform both</p>
237
</div>
238

239
<!-- Child targeting -->
240
<nav class="*:px-4 *:py-2 *:rounded">
241
  <a href="#">All children get padding and rounded corners</a>
242
  <a href="#">Automatically applied</a>
243
</nav>
244
```
245

246
### Container Query Variants
247

248
Modern container query support for component-based responsive design.
249

250
**Container Variants:**
251
- `@container:` - Container query support
252
- `@xs:`, `@sm:`, `@md:`, `@lg:`, `@xl:` - Container-based breakpoints
253
- Requires container configuration in theme
254

255
**Usage Example:**
256

257
```html
258
<div class="@container">
259
  <div class="@md:flex @md:space-x-4">
260
    Content that responds to container size
261
  </div>
262
</div>
263
```
264

265
### Media Query Variants
266

267
Custom media query variants for advanced responsive design.
268

269
**Print Variants:**
270
- `print:` - `@media print`
271

272
**Motion Preferences:**
273
- `motion-safe:` - `@media (prefers-reduced-motion: no-preference)`
274
- `motion-reduce:` - `@media (prefers-reduced-motion: reduce)`
275

276
**Custom Media Queries:**
277
- Configurable through theme `media` configuration
278

279
### CSS Supports Variants
280

281
Feature query variants for progressive enhancement.
282

283
**Supports Variants:**
284
- `supports-[property:value]:` - `@supports (property: value)`
285
- Configurable through theme `supports` configuration
286

287
**Usage Example:**
288

289
```html
290
<div class="grid supports-[display:subgrid]:subgrid">
291
  Falls back to grid, uses subgrid if supported
292
</div>
293
```
294

295
### Arbitrary Variants
296

297
Powerful arbitrary variant syntax for custom selectors when `arbitraryVariants` is enabled.
298

299
**Arbitrary Syntax:**
300
- `[selector]:` - Custom CSS selector
301
- `[&>*]:` - Target direct children
302
- `[&[attr]]:` - Target elements with attributes
303
- `[.parent_&]:` - Custom parent selector
304

305
**Usage Examples:**
306

307
```html
308
<!-- Target all children -->
309
<div class="[&>*]:margin-4">
310
  All direct children get margin
311
</div>
312

313
<!-- Complex selectors -->
314
<details class="[&[open]>summary]:text-blue-600">
315
  <summary>Click to expand</summary>
316
  <p>Content</p>
317
</details>
318

319
<!-- Parent-based styling -->
320
<div class="[.sidebar_&]:hidden">
321
  Hidden when inside .sidebar
322
</div>
323
```
324

325
### Important Modifier
326

327
Force important on any utility with the `!` prefix.
328

329
**Important Variants:**
330
- `!` - Adds `!important` to CSS declarations
331

332
**Usage Example:**
333

334
```html
335
<div class="!text-red-500">
336
  This text color cannot be overridden
337
</div>
338
```
339

340
### Negative Value Variants
341

342
Automatic negative value support for applicable utilities.
343

344
**Negative Variants:**
345
- `-` prefix for negative values
346
- Applied automatically to spacing, transforms, etc.
347

348
**Usage Example:**
349

350
```html
351
<div class="-mt-4 -translate-x-2">
352
  Negative margin and transform
353
</div>
354
```
355

356
## Variant Stacking
357

358
Variants can be combined and stacked for complex conditional styling:
359

360
```html
361
<!-- Multiple variants -->
362
<button class="md:hover:focus:bg-blue-600 dark:md:hover:bg-gray-700">
363
  Complex conditional styling
364
</button>
365

366
<!-- Arbitrary with standard variants -->
367
<div class="hover:[&>*]:scale-110 focus-within:[&>*]:opacity-75">
368
  Combined arbitrary and standard variants
369
</div>
370
```
371

372
## Configuration Integration
373

374
Variants respect preset configuration options:
375

376
- `dark` option affects dark mode variant behavior
377
- `attributifyPseudo` changes group/peer selector generation
378
- `arbitraryVariants` enables/disables arbitrary variant syntax
379
- Theme configuration extends available breakpoints, media queries, etc.