0
# Safelist Configuration
1

2
Advanced safelist system with multiple patterns for protecting selectors from removal, plus blocklist functionality for forced removal.
3

4
## Capabilities
5

6
### Safelist Types
7

8
Union type representing user-defined safelist configurations.
9

10
```typescript { .api }
11
type UserDefinedSafelist = StringRegExpArray | ComplexSafelist;
12

13
type StringRegExpArray = Array<RegExp | string>;
14
```
15

16
### Complex Safelist Interface
17

18
Comprehensive safelist configuration with multiple protection strategies.
19

20
```typescript { .api }
21
interface ComplexSafelist {
22
  /** Standard safelist - exact matches and RegExp patterns for selectors */
23
  standard?: StringRegExpArray;
24
  /** Deep safelist - protect selectors and all their children */
25
  deep?: RegExp[];
26
  /** Greedy safelist - protect any selector part matching these patterns */
27
  greedy?: RegExp[];
28
  /** Variables safelist - protect CSS custom properties */
29
  variables?: StringRegExpArray;
30
  /** Keyframes safelist - protect @keyframes animations */
31
  keyframes?: StringRegExpArray;
32
}
33
```
34

35
### Safelist Standardization
36

37
Utility function to normalize user-defined safelist into consistent format.
38

39
```typescript { .api }
40
/**
41
 * Format the user defined safelist into a standardized safelist object
42
 * @param userDefinedSafelist - User defined safelist configuration
43
 * @returns Formatted safelist object with all properties defined
44
 */
45
function standardizeSafelist(
46
  userDefinedSafelist?: UserDefinedSafelist
47
): Required<ComplexSafelist>;
48
```
49

50
## Safelist Patterns
51

52
### Standard Safelist
53

54
Protects selectors that match exactly or via RegExp patterns.
55

56
**Usage Examples:**
57

58
```typescript
59
import { PurgeCSS } from "purgecss";
60

61
// String array format
62
const results = await new PurgeCSS().purge({
63
  content: ['index.html'],
64
  css: ['styles.css'],
65
  safelist: ['btn', 'btn-primary', 'navbar']
66
});
67

68
// Complex object format with standard patterns
69
const results2 = await new PurgeCSS().purge({
70
  content: ['index.html'],
71
  css: ['styles.css'],
72
  safelist: {
73
    standard: ['btn', /^btn-/, /modal$/]
74
  }
75
});
76
```
77

78
### Deep Safelist
79

80
Protects selectors and all their descendant selectors based on RegExp patterns.
81

82
```typescript { .api }
83
interface ComplexSafelist {
84
  /**
85
   * You can safelist selectors and their children based on a regular
86
   * expression with `safelist.deep`
87
   * 
88
   * In this example, selectors such as `.bg-red .child-of-bg` will be left
89
   * in the final CSS, even if `child-of-bg` is not found.
90
   */
91
  deep?: RegExp[];
92
}
93
```
94

95
**Usage Example:**
96

97
```typescript
98
const results = await new PurgeCSS().purge({
99
  content: [],
100
  css: ['styles.css'],
101
  safelist: {
102
    deep: [/red$/]  // Protects .bg-red and all its children like .bg-red .child-of-bg
103
  }
104
});
105
```
106

107
### Greedy Safelist
108

109
Protects any selector if any part of it matches the RegExp patterns.
110

111
**Usage Example:**
112

113
```typescript
114
const results = await new PurgeCSS().purge({
115
  content: ['index.html'],
116
  css: ['styles.css'],
117
  safelist: {
118
    greedy: [/^data-/, /^js-/]  // Protects any selector containing data- or js- attributes
119
  }
120
});
121
```
122

123
### Variables Safelist
124

125
Protects CSS custom properties (variables) from removal.
126

127
**Usage Example:**
128

129
```typescript
130
const results = await new PurgeCSS().purge({
131
  content: ['index.html'],
132
  css: ['styles.css'],
133
  variables: true,
134
  safelist: {
135
    variables: ['--primary-color', /^--theme-/]
136
  }
137
});
138
```
139

140
### Keyframes Safelist
141

142
Protects @keyframes animations from removal.
143

144
**Usage Example:**
145

146
```typescript
147
const results = await new PurgeCSS().purge({
148
  content: ['index.html'],
149
  css: ['styles.css'],
150
  keyframes: true,
151
  safelist: {
152
    keyframes: ['fadeIn', /^slide/]
153
  }
154
});
155
```
156

157
## Blocklist Configuration
158

159
Blocklist functionality for forcing removal of specific selectors even if they are found in content.
160

161
```typescript { .api }
162
type StringRegExpArray = Array<RegExp | string>;
163
```
164

165
**Usage Example:**
166

167
```typescript
168
const results = await new PurgeCSS().purge({
169
  content: ['index.html'],
170
  css: ['styles.css'],
171
  blocklist: ['debug', 'temp', /^test-/]  // Force remove these selectors
172
});
173
```
174

175
## Advanced Safelist Patterns
176

177
### Combining Multiple Safelist Types
178

179
```typescript
180
const results = await new PurgeCSS().purge({
181
  content: ['src/**/*.html', 'src/**/*.js'],
182
  css: ['styles/*.css'],
183
  variables: true,
184
  keyframes: true,
185
  fontFace: true,
186
  safelist: {
187
    standard: ['btn', 'navbar', /^alert-/],
188
    deep: [/^theme-/, /^layout-/],
189
    greedy: [/^data-/, /^js-hook/],
190
    variables: ['--primary', '--secondary', /^--color-/],
191
    keyframes: ['fadeIn', 'slideOut', /^bounce/]
192
  },
193
  blocklist: [/^debug-/, 'temp-class']
194
});
195
```
196

197
### Dynamic Attributes Protection
198

199
PurgeCSS automatically protects certain dynamic HTML attributes that can change based on user interaction.
200

201
```typescript { .api }
202
interface UserDefinedOptions {
203
  /** Custom CSS attribute selectors to preserve */
204
  dynamicAttributes?: string[];
205
}
206
```
207

208
**Built-in protected attributes:**
209
- `value` - Form input values
210
- `checked` - Checkbox/radio states  
211
- `selected` - Select option states
212
- `open` - Details/summary states
213

214
**Usage Example:**
215

216
```typescript
217
const results = await new PurgeCSS().purge({
218
  content: ['index.html'],
219
  css: ['styles.css'],
220
  dynamicAttributes: ['aria-expanded', 'data-active', 'data-state']
221
});
222
```
223

224
## Internal Safelist
225

226
PurgeCSS includes an internal safelist of selectors that are always preserved:
227

228
```typescript
229
const CSS_SAFELIST = ["*", ":root", ":after", ":before"];
230
```
231

232
These selectors are fundamental to CSS functionality and are automatically protected regardless of user configuration.