0
# UnoCSS
1

2
UnoCSS is an instant on-demand atomic CSS engine that revolutionizes CSS development by generating styles dynamically based on class usage without parsing, AST, or scanning. It offers complete customization through presets rather than core utilities, supports multiple integration methods, and provides advanced features for efficient, on-demand CSS generation.
3

4
## Package Information
5

6
- **Package Name**: unocss
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install unocss`
10

11
## Core Imports
12

13
```typescript
14
import { defineConfig, createGenerator } from "unocss";
15
import { presetUno, presetAttributify, presetIcons } from "unocss";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { defineConfig, createGenerator, presetUno } = require("unocss");
22
```
23

24
## Basic Usage
25

26
```typescript
27
import { defineConfig, presetUno, presetAttributify } from "unocss";
28

29
// Define UnoCSS configuration
30
export default defineConfig({
31
  presets: [
32
    presetUno(), // Essential utilities
33
    presetAttributify(), // Attributify mode
34
  ],
35
  rules: [
36
    // Custom rule
37
    ["m-1", { margin: "0.25rem" }]
38
  ],
39
  shortcuts: {
40
    // Custom shortcut
41
    "btn": "py-2 px-4 font-semibold rounded-lg shadow-md"
42
  }
43
});
44

45
// Create generator programmatically
46
const generator = await createGenerator({
47
  presets: [presetUno()]
48
});
49

50
const { css } = await generator.generate("text-red-500 bg-blue-200");
51
console.log(css);
52
```
53

54
## Architecture
55

56
UnoCSS is built around several key components:
57

58
- **Core Engine**: Generator and configuration system for atomic CSS generation
59
- **Preset System**: Modular CSS utility collections (Uno, Wind, Mini, Attributify, Icons, Typography)
60
- **Transformer System**: Source code transformers for advanced features (directives, variant groups)
61
- **Integration Layer**: Build tool plugins for Vite, Webpack, PostCSS, and Astro
62
- **Configuration API**: Type-safe configuration with defineConfig helper
63

64
## Capabilities
65

66
### Core Engine
67

68
Core UnoCSS engine functionality for generator creation, configuration management, and CSS generation.
69

70
```typescript { .api }
71
function defineConfig<Theme>(config: UserConfig<Theme>): UserConfig<Theme>;
72
function createGenerator<Theme>(config?: UserConfig<Theme>, defaults?: UserConfig<Theme>): Promise<UnoGenerator<Theme>>;
73
```
74

75
[Core Engine](./core-engine.md)
76

77
### CSS Presets
78

79
Pre-built CSS utility collections providing different atomic CSS methodologies and frameworks.
80

81
```typescript { .api }
82
function presetUno(options?: PresetUnoOptions): Preset<PresetUnoTheme>;
83
function presetMini(options?: PresetMiniOptions): Preset<PresetMiniTheme>;
84
function presetWind(options?: PresetWindOptions): Preset<PresetWindTheme>;
85
function presetAttributify(options?: AttributifyOptions): Preset;
86
function presetIcons(options?: IconsOptions): Preset;
87
function presetTypography(options?: TypographyOptions): Preset;
88
```
89

90
[CSS Presets](./presets.md)
91

92
### Source Code Transformers
93

94
Transformers that process source code to enable advanced UnoCSS features and syntax.
95

96
```typescript { .api }
97
function transformerDirectives(options?: TransformerDirectivesOptions): SourceCodeTransformer;
98
function transformerVariantGroup(options?: TransformerVariantGroupOptions): SourceCodeTransformer;
99
function transformerAttributifyJsx(options?: object): SourceCodeTransformer;
100
function transformerCompileClass(options?: object): SourceCodeTransformer;
101
```
102

103
[Source Code Transformers](./transformers.md)
104

105
### Build Tool Integrations
106

107
Integration plugins for popular build tools and frameworks.
108

109
```typescript { .api }
110
// Vite Plugin
111
export default function UnocssVitePlugin<Theme>(
112
  configOrPath?: VitePluginConfig<Theme> | string
113
): Plugin[];
114

115
// Astro Integration
116
export default function UnocssAstroIntegration<Theme>(
117
  config?: AstroIntegrationConfig<Theme>
118
): AstroIntegration;
119

120
// Webpack Plugin
121
export default function UnocssWebpackPlugin<Theme>(
122
  configOrPath?: WebpackPluginOptions<Theme> | string
123
): any;
124

125
// PostCSS Plugin
126
export default function unocss(options?: object): any;
127
```
128

129
[Build Tool Integrations](./integrations.md)
130

131
## Types
132

133
### Core Configuration Types
134

135
```typescript { .api }
136
interface UserConfig<Theme = object> {
137
  /** List of presets to use */
138
  presets?: Preset<Theme>[] | Preset<Theme>;
139
  /** Custom CSS rules */
140
  rules?: Rule<Theme>[];
141
  /** CSS shortcuts */
142
  shortcuts?: UserShortcuts<Theme>;
143
  /** Custom variants */
144
  variants?: Variant<Theme>[];
145
  /** CSS extractors */
146
  extractors?: Extractor[];
147
  /** Source code transformers */
148
  transformers?: SourceCodeTransformer[];
149
  /** Preflight CSS */
150
  preflights?: Preflight<Theme>[];
151
  /** CSS layers configuration */
152
  layers?: Record<string, number>;
153
  /** Theme configuration */
154
  theme?: Theme;
155
  /** Files to include/exclude */
156
  include?: FilterPattern;
157
  exclude?: FilterPattern;
158
  /** Safelist of classes to always include */
159
  safelist?: string[] | string;
160
  /** Blocklist of classes to exclude */
161
  blocklist?: (string | RegExp)[];
162
}
163

164
interface ResolvedConfig<Theme = object> extends Required<UserConfig<Theme>> {
165
  /** Resolved shortcuts */
166
  shortcuts: Shortcut<Theme>[];
167
}
168

169
interface Preset<Theme = object> {
170
  name?: string;
171
  enforce?: 'pre' | 'post';
172
  presets?: Preset<Theme>[];
173
  rules?: Rule<Theme>[];
174
  shortcuts?: UserShortcuts<Theme>;
175
  variants?: Variant<Theme>[];
176
  extractors?: Extractor[];
177
  preflights?: Preflight<Theme>[];
178
  theme?: Theme;
179
  layers?: Record<string, number>;
180
  options?: PresetOptions;
181
}
182
```
183

184
### Utility Types
185

186
```typescript { .api }
187
type Awaitable<T> = T | Promise<T>;
188
type Arrayable<T> = T | T[];
189
type DeepPartial<T> = { [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P] };
190
type FilterPattern = string | RegExp | (string | RegExp)[];
191

192
type Rule<Theme = object> = 
193
  | [string, CSSObject | CSSEntries]
194
  | [RegExp, (match: RegExpMatchArray, context: RuleContext<Theme>) => Awaitable<CSSObject | CSSEntries | string | undefined>];
195

196
type Variant<Theme = object> = 
197
  | [string | RegExp, (input: VariantHandlerContext, context: VariantContext<Theme>) => Awaitable<VariantHandlerReturn>];
198

199
type CSSObject = Record<string, string | number | CSSObject>;
200
type CSSEntries = [string, string | number][];
201
```