UnoCSS Rules
Rules define utility classes and the CSS they generate. UnoCSS has many built-in rules via presets and allows custom rules.
Static Rules
Simple mapping from class name to CSS properties:
rules: [
['m-1', { margin: '0.25rem' }],
['font-bold', { 'font-weight': 700 }],
]Usage: <div class="m-1"> generates .m-1 { margin: 0.25rem; }
Note: Use CSS property syntax with hyphens (e.g., font-weight not fontWeight). Quote properties with hyphens.
Dynamic Rules
Use RegExp matcher with function body for flexible utilities:
rules: [
// Match m-1, m-2, m-100, etc.
[/^m-(\d+)$/, ([, d]) => ({ margin: `${d / 4}rem` })],
// Access theme and context
[/^p-(\d+)$/, (match, ctx) => ({ padding: `${match[1] / 4}rem` })],
]The function receives:
- RegExp match result (destructure to get captured groups)
- Context object with
theme,symbols, etc.
CSS Fallback Values
Return 2D array for CSS property fallbacks (browser compatibility):
rules: [
[/^h-(\d+)dvh$/, ([_, d]) => [
['height', `${d}vh`],
['height', `${d}dvh`],
]],
]Generates: .h-100dvh { height: 100vh; height: 100dvh; }
Special Symbols
Control CSS output with symbols from @unocss/core:
import { symbols } from '@unocss/core'
rules: [
['grid', {
[symbols.parent]: '@supports (display: grid)',
display: 'grid',
}],
]Available Symbols
| Symbol | Description |
|---|---|
symbols.parent |
Parent wrapper (e.g., @supports, @media) |
symbols.selector |
Function to modify the selector |
symbols.layer |
Set the UnoCSS layer |
symbols.variants |
Array of variant handlers |
symbols.shortcutsNoMerge |
Disable merging in shortcuts |
symbols.noMerge |
Disable rule merging |
symbols.sort |
Override sorting order |
symbols.body |
Full control of CSS body |
Multi-Selector Rules
Use generator functions to yield multiple CSS rules:
rules: [
[/^button-(.*)$/, function* ([, color], { symbols }) {
yield { background: color }
yield {
[symbols.selector]: selector => `${selector}:hover`,
background: `color-mix(in srgb, ${color} 90%, black)`
}
}],
]Generates both .button-red { background: red; } and .button-red:hover { ... }
Fully Controlled Rules
Return a string for complete CSS control (advanced):
import { defineConfig, toEscapedSelector as e } from 'unocss'
rules: [
[/^custom-(.+)$/, ([, name], { rawSelector, theme }) => {
const selector = e(rawSelector)
return `
${selector} { font-size: ${theme.fontSize.sm}; }
${selector}::after { content: 'after'; }
@media (min-width: ${theme.breakpoints.sm}) {
${selector} { font-size: ${theme.fontSize.lg}; }
}
`
}],
]Warning: Fully controlled rules don't work with variants like hover:.
Symbols.body for Variant Support
Use symbols.body to keep variant support with custom CSS:
rules: [
['custom-red', {
[symbols.body]: `
font-size: 1rem;
&::after { content: 'after'; }
& > .bar { color: red; }
`,
[symbols.selector]: selector => `:is(${selector})`,
}]
]Rule Ordering
Later rules have higher priority. Dynamic rules output is sorted alphabetically within the group.
Rule Merging
UnoCSS merges rules with identical CSS bodies:
<div class="m-2 hover:m2">Generates:
.hover\:m2:hover, .m-2 { margin: 0.5rem; }Use symbols.noMerge to disable.