1---
2name: unocss-rules
3description: Static and dynamic rules for generating CSS utilities in UnoCSS
4---
5 
6# UnoCSS Rules
7 
8Rules define utility classes and the CSS they generate. UnoCSS has many built-in rules via presets and allows custom rules.
9 
10## Static Rules
11 
12Simple mapping from class name to CSS properties:
13 
14```ts
15rules: [
16  ['m-1', { margin: '0.25rem' }],
17  ['font-bold', { 'font-weight': 700 }],
18]
19```
20 
21Usage: `<div class="m-1">` generates `.m-1 { margin: 0.25rem; }`
22 
23**Note:** Use CSS property syntax with hyphens (e.g., `font-weight` not `fontWeight`). Quote properties with hyphens.
24 
25## Dynamic Rules
26 
27Use RegExp matcher with function body for flexible utilities:
28 
29```ts
30rules: [
31  // Match m-1, m-2, m-100, etc.
32  [/^m-(\d+)$/, ([, d]) => ({ margin: `${d / 4}rem` })],
33  
34  // Access theme and context
35  [/^p-(\d+)$/, (match, ctx) => ({ padding: `${match[1] / 4}rem` })],
36]
37```
38 
39The function receives:
401. RegExp match result (destructure to get captured groups)
412. Context object with `theme`, `symbols`, etc.
42 
43## CSS Fallback Values
44 
45Return 2D array for CSS property fallbacks (browser compatibility):
46 
47```ts
48rules: [
49  [/^h-(\d+)dvh$/, ([_, d]) => [
50    ['height', `${d}vh`],
51    ['height', `${d}dvh`],
52  ]],
53]
54```
55 
56Generates: `.h-100dvh { height: 100vh; height: 100dvh; }`
57 
58## Special Symbols
59 
60Control CSS output with symbols from `@unocss/core`:
61 
62```ts
63import { symbols } from '@unocss/core'
64 
65rules: [
66  ['grid', {
67    [symbols.parent]: '@supports (display: grid)',
68    display: 'grid',
69  }],
70]
71```
72 
73### Available Symbols
74 
75| Symbol | Description |
76|--------|-------------|
77| `symbols.parent` | Parent wrapper (e.g., `@supports`, `@media`) |
78| `symbols.selector` | Function to modify the selector |
79| `symbols.layer` | Set the UnoCSS layer |
80| `symbols.variants` | Array of variant handlers |
81| `symbols.shortcutsNoMerge` | Disable merging in shortcuts |
82| `symbols.noMerge` | Disable rule merging |
83| `symbols.sort` | Override sorting order |
84| `symbols.body` | Full control of CSS body |
85 
86## Multi-Selector Rules
87 
88Use generator functions to yield multiple CSS rules:
89 
90```ts
91rules: [
92  [/^button-(.*)$/, function* ([, color], { symbols }) {
93    yield { background: color }
94    yield {
95      [symbols.selector]: selector => `${selector}:hover`,
96      background: `color-mix(in srgb, ${color} 90%, black)`
97    }
98  }],
99]
100```
101 
102Generates both `.button-red { background: red; }` and `.button-red:hover { ... }`
103 
104## Fully Controlled Rules
105 
106Return a string for complete CSS control (advanced):
107 
108```ts
109import { defineConfig, toEscapedSelector as e } from 'unocss'
110 
111rules: [
112  [/^custom-(.+)$/, ([, name], { rawSelector, theme }) => {
113    const selector = e(rawSelector)
114    return `
115${selector} { font-size: ${theme.fontSize.sm}; }
116${selector}::after { content: 'after'; }
117@media (min-width: ${theme.breakpoints.sm}) {
118  ${selector} { font-size: ${theme.fontSize.lg}; }
119}
120`
121  }],
122]
123```
124 
125**Warning:** Fully controlled rules don't work with variants like `hover:`.
126 
127## Symbols.body for Variant Support
128 
129Use `symbols.body` to keep variant support with custom CSS:
130 
131```ts
132rules: [
133  ['custom-red', {
134    [symbols.body]: `
135      font-size: 1rem;
136      &::after { content: 'after'; }
137      & > .bar { color: red; }
138    `,
139    [symbols.selector]: selector => `:is(${selector})`,
140  }]
141]
142```
143 
144## Rule Ordering
145 
146Later rules have higher priority. Dynamic rules output is sorted alphabetically within the group.
147 
148## Rule Merging
149 
150UnoCSS merges rules with identical CSS bodies:
151 
152```html
153<div class="m-2 hover:m2">
154```
155 
156Generates:
157```css
158.hover\:m2:hover, .m-2 { margin: 0.5rem; }
159```
160 
161Use `symbols.noMerge` to disable.
162 
163<!-- 
164Source references:
165- https://unocss.dev/config/rules
166-->
167