1---
2name: unocss-safelist-blocklist
3description: Force include or exclude specific utilities
4---
5 
6# Safelist and Blocklist
7 
8Control which utilities are always included or excluded.
9 
10## Safelist
11 
12Utilities always included, regardless of detection:
13 
14```ts
15export default defineConfig({
16  safelist: [
17    'p-1', 'p-2', 'p-3',
18    // Dynamic generation
19    ...Array.from({ length: 4 }, (_, i) => `p-${i + 1}`),
20  ],
21})
22```
23 
24### Function Form
25 
26```ts
27safelist: [
28  'p-1',
29  () => ['m-1', 'm-2'],
30  (context) => {
31    const colors = Object.keys(context.theme.colors || {})
32    return colors.map(c => `bg-${c}-500`)
33  },
34]
35```
36 
37### Common Use Cases
38 
39```ts
40safelist: [
41  // Dynamic colors from CMS
42  () => ['primary', 'secondary'].flatMap(c => [
43    `bg-${c}`, `text-${c}`, `border-${c}`,
44  ]),
45  
46  // Component variants
47  () => {
48    const variants = ['primary', 'danger']
49    const sizes = ['sm', 'md', 'lg']
50    return variants.flatMap(v => sizes.map(s => `btn-${v}-${s}`))
51  },
52]
53```
54 
55## Blocklist
56 
57Utilities never generated:
58 
59```ts
60blocklist: [
61  'p-1',           // Exact match
62  /^p-[2-4]$/,     // Regex
63]
64```
65 
66### With Messages
67 
68```ts
69blocklist: [
70  ['bg-red-500', { message: 'Use bg-red-600 instead' }],
71  [/^text-xs$/, { message: 'Use text-sm for accessibility' }],
72]
73```
74 
75## Safelist vs Blocklist
76 
77| Feature | Safelist | Blocklist |
78|---------|----------|-----------|
79| Purpose | Always include | Always exclude |
80| Strings | ✅ | ✅ |
81| Regex | ❌ | ✅ |
82| Functions | ✅ | ❌ |
83 
84**Note:** Blocklist wins if utility is in both.
85 
86## Best Practice
87 
88Prefer static mappings over safelist:
89 
90```ts
91// Better: UnoCSS extracts automatically
92const sizes = {
93  sm: 'text-sm p-2',
94  md: 'text-base p-4',
95}
96 
97// Avoid: Large safelist
98safelist: ['text-sm', 'text-base', 'p-2', 'p-4']
99```
100 
101<!-- 
102Source references:
103- https://unocss.dev/config/safelist
104- https://unocss.dev/guide/extracting
105-->
106