---
name: unocss-safelist-blocklist
description: Force include or exclude specific utilities
---

# Safelist and Blocklist

Control which utilities are always included or excluded.

## Safelist

Utilities always included, regardless of detection:

```ts
export default defineConfig({
  safelist: [
    'p-1', 'p-2', 'p-3',
    // Dynamic generation
    ...Array.from({ length: 4 }, (_, i) => `p-${i + 1}`),
  ],
})
```

### Function Form

```ts
safelist: [
  'p-1',
  () => ['m-1', 'm-2'],
  (context) => {
    const colors = Object.keys(context.theme.colors || {})
    return colors.map(c => `bg-${c}-500`)
  },
]
```

### Common Use Cases

```ts
safelist: [
  // Dynamic colors from CMS
  () => ['primary', 'secondary'].flatMap(c => [
    `bg-${c}`, `text-${c}`, `border-${c}`,
  ]),
  
  // Component variants
  () => {
    const variants = ['primary', 'danger']
    const sizes = ['sm', 'md', 'lg']
    return variants.flatMap(v => sizes.map(s => `btn-${v}-${s}`))
  },
]
```

## Blocklist

Utilities never generated:

```ts
blocklist: [
  'p-1',           // Exact match
  /^p-[2-4]$/,     // Regex
]
```

### With Messages

```ts
blocklist: [
  ['bg-red-500', { message: 'Use bg-red-600 instead' }],
  [/^text-xs$/, { message: 'Use text-sm for accessibility' }],
]
```

## Safelist vs Blocklist

| Feature | Safelist | Blocklist |
|---------|----------|-----------|
| Purpose | Always include | Always exclude |
| Strings | ✅ | ✅ |
| Regex | ❌ | ✅ |
| Functions | ✅ | ❌ |

**Note:** Blocklist wins if utility is in both.

## Best Practice

Prefer static mappings over safelist:

```ts
// Better: UnoCSS extracts automatically
const sizes = {
  sm: 'text-sm p-2',
  md: 'text-base p-4',
}

// Avoid: Large safelist
safelist: ['text-sm', 'text-base', 'p-2', 'p-4']
```

<!-- 
Source references:
- https://unocss.dev/config/safelist
- https://unocss.dev/guide/extracting
-->