1---
2name: unocss-configuration
3description: Config file setup and all configuration options for UnoCSS
4---
5 
6# UnoCSS Configuration
7 
8UnoCSS is configured via a dedicated config file in your project root.
9 
10## Config File
11 
12**Recommended:** Use a dedicated `uno.config.ts` file for best IDE support and HMR.
13 
14```ts
15// uno.config.ts
16import {
17  defineConfig,
18  presetAttributify,
19  presetIcons,
20  presetTypography,
21  presetWebFonts,
22  presetWind3,
23  transformerDirectives,
24  transformerVariantGroup
25} from 'unocss'
26 
27export default defineConfig({
28  shortcuts: [
29    // ...
30  ],
31  theme: {
32    colors: {
33      // ...
34    }
35  },
36  presets: [
37    presetWind3(),
38    presetAttributify(),
39    presetIcons(),
40    presetTypography(),
41    presetWebFonts({
42      fonts: {
43        // ...
44      },
45    }),
46  ],
47  transformers: [
48    transformerDirectives(),
49    transformerVariantGroup(),
50  ],
51})
52```
53 
54UnoCSS automatically looks for `uno.config.{js,ts,mjs,mts}` or `unocss.config.{js,ts,mjs,mts}` in the project root.
55 
56## Key Configuration Options
57 
58### rules
59Define CSS utility rules. Later entries have higher priority.
60 
61```ts
62rules: [
63  ['m-1', { margin: '0.25rem' }],
64  [/^m-(\d+)$/, ([, d]) => ({ margin: `${d / 4}rem` })],
65]
66```
67 
68### shortcuts
69Combine multiple rules into a single shorthand.
70 
71```ts
72shortcuts: {
73  'btn': 'py-2 px-4 font-semibold rounded-lg shadow-md',
74}
75```
76 
77### theme
78Theme object for design tokens shared between rules.
79 
80```ts
81theme: {
82  colors: {
83    brand: '#942192',
84  },
85  breakpoints: {
86    sm: '640px',
87    md: '768px',
88  },
89}
90```
91 
92### presets
93Predefined configurations bundling rules, variants, and themes.
94 
95```ts
96presets: [
97  presetWind3(),
98  presetIcons(),
99]
100```
101 
102### transformers
103Transform source code to support special syntax.
104 
105```ts
106transformers: [
107  transformerDirectives(),
108  transformerVariantGroup(),
109]
110```
111 
112### variants
113Preprocess selectors with ability to rewrite CSS output.
114 
115### extractors
116Handle source files and extract utility class names.
117 
118### preflights
119Inject raw CSS globally.
120 
121### layers
122Control the order of CSS layers. Default is `0`.
123 
124```ts
125layers: {
126  'components': -1,
127  'default': 1,
128  'utilities': 2,
129}
130```
131 
132### safelist
133Utilities that are always included in output.
134 
135```ts
136safelist: ['p-1', 'p-2', 'p-3']
137```
138 
139### blocklist
140Utilities that are always excluded.
141 
142```ts
143blocklist: ['p-1', /^p-[2-4]$/]
144```
145 
146### content
147Configure where to extract utilities from.
148 
149```ts
150content: {
151  pipeline: {
152    include: [/\.(vue|svelte|tsx|html)($|\?)/],
153  },
154  filesystem: ['src/**/*.php'],
155}
156```
157 
158### separators
159Variant separator characters. Default: `[':', '-']`
160 
161### outputToCssLayers
162Output UnoCSS layers as CSS Cascade Layers.
163 
164```ts
165outputToCssLayers: true
166```
167 
168## Specifying Config File Location
169 
170```ts
171// vite.config.ts
172import UnoCSS from 'unocss/vite'
173 
174export default defineConfig({
175  plugins: [
176    UnoCSS({
177      configFile: '../my-uno.config.ts',
178    }),
179  ],
180})
181```
182 
183<!-- 
184Source references:
185- https://unocss.dev/guide/config-file
186- https://unocss.dev/config/
187-->
188