1---
2name: unocss-variants
3description: Apply variations like hover:, dark:, responsive to rules
4---
5 
6# UnoCSS Variants
7 
8Variants apply modifications to utility rules, like `hover:`, `dark:`, or responsive prefixes.
9 
10## How Variants Work
11 
12When matching `hover:m-2`:
13 
141. `hover:m-2` is extracted from source
152. Sent to all variants for matching
163. `hover:` variant matches and returns `m-2`
174. Result `m-2` continues to next variants
185. Finally matches the rule `.m-2 { margin: 0.5rem; }`
196. Variant transformation applied: `.hover\:m-2:hover { margin: 0.5rem; }`
20 
21## Creating Custom Variants
22 
23```ts
24variants: [
25  // hover: variant
26  (matcher) => {
27    if (!matcher.startsWith('hover:'))
28      return matcher
29    return {
30      // Remove prefix, pass to next variants/rules
31      matcher: matcher.slice(6),
32      // Modify the selector
33      selector: s => `${s}:hover`,
34    }
35  },
36],
37rules: [
38  [/^m-(\d)$/, ([, d]) => ({ margin: `${d / 4}rem` })],
39]
40```
41 
42## Variant Return Object
43 
44- `matcher` - The processed class name to pass forward
45- `selector` - Function to customize the CSS selector
46- `parent` - Wrapper like `@media`, `@supports`
47- `layer` - Specify output layer
48- `sort` - Control ordering
49 
50## Built-in Variants (preset-wind3)
51 
52### Pseudo-classes
53- `hover:`, `focus:`, `active:`, `visited:`
54- `first:`, `last:`, `odd:`, `even:`
55- `disabled:`, `checked:`, `required:`
56- `focus-within:`, `focus-visible:`
57 
58### Pseudo-elements
59- `before:`, `after:`
60- `placeholder:`, `selection:`
61- `marker:`, `file:`
62 
63### Responsive
64- `sm:`, `md:`, `lg:`, `xl:`, `2xl:`
65- `lt-sm:` (less than sm)
66- `at-lg:` (at lg only)
67 
68### Dark Mode
69- `dark:` - Class-based dark mode (default)
70- `@dark:` - Media query dark mode
71 
72### Group/Peer
73- `group-hover:`, `group-focus:`
74- `peer-checked:`, `peer-focus:`
75 
76### Container Queries
77- `@container`, `@sm:`, `@md:`
78 
79### Print
80- `print:`
81 
82### Supports
83- `supports-[display:grid]:`
84 
85### Aria
86- `aria-checked:`, `aria-disabled:`
87 
88### Data Attributes
89- `data-[state=open]:`
90 
91## Dark Mode Configuration
92 
93### Class-based (default)
94```ts
95presetWind3({
96  dark: 'class'
97})
98```
99 
100```html
101<div class="dark:bg-gray-800">
102```
103 
104Generates: `.dark .dark\:bg-gray-800 { ... }`
105 
106### Media Query
107```ts
108presetWind3({
109  dark: 'media'
110})
111```
112 
113Generates: `@media (prefers-color-scheme: dark) { ... }`
114 
115### Opt-in Media Query
116Use `@dark:` regardless of config:
117 
118```html
119<div class="@dark:bg-gray-800">
120```
121 
122### Custom Selectors
123```ts
124presetWind3({
125  dark: {
126    light: '.light-mode',
127    dark: '.dark-mode',
128  }
129})
130```
131 
132## CSS @layer Variant
133 
134Native CSS `@layer` support:
135 
136```html
137<div class="layer-foo:p-4" />
138```
139 
140Generates:
141```css
142@layer foo {
143  .layer-foo\:p-4 { padding: 1rem; }
144}
145```
146 
147## Breakpoint Differences from Windi CSS
148 
149| Windi CSS | UnoCSS |
150|-----------|--------|
151| `<sm:p-1` | `lt-sm:p-1` |
152| `@lg:p-1` | `at-lg:p-1` |
153| `>xl:p-1` | `xl:p-1` |
154 
155## Media Hover (Experimental)
156 
157Addresses sticky hover on touch devices:
158 
159```html
160<div class="@hover-text-red">
161```
162 
163Generates:
164```css
165@media (hover: hover) and (pointer: fine) {
166  .\@hover-text-red:hover { color: rgb(248 113 113); }
167}
168```
169 
170<!-- 
171Source references:
172- https://unocss.dev/config/variants
173- https://unocss.dev/presets/wind3
174- https://unocss.dev/presets/mini
175-->
176