Safelist

Safelist is an important option in UnoCSS configuration that allows you to specify a set of utility classes that should always be included in the generated CSS, regardless of whether these classes are detected in your source code.

Basic Usage

String Array

The simplest usage is to provide a string array containing the class names you want to preserve:

// uno.config.ts
export default defineConfig({
  safelist: [
    'p-1',
    'p-2',
    'p-3',
    'text-center',
    'bg-red-500'
  ]
})

Function Form

Safelist can also contain functions that are called during build time and can dynamically return class names:

// uno.config.ts
export default defineConfig({
  safelist: [
    // Static class names
    'p-1',
    'p-2',
    // Dynamic function
    context => ['m-1', 'm-2', 'm-3'],
    (context) => {
      // Generate class names based on theme
      const colors = Object.keys(context.theme.colors || {})
      return colors.map(color => `bg-${color}-500`)
    }
  ]
})

Mixed Usage

You can mix strings and functions in the same safelist configuration:

// uno.config.ts
export default defineConfig({
  safelist: [
    // Static class names
    'prose',
    'bg-orange-300',
    // Dynamic generation
    () => ['flex', 'grid', 'block'],
    // Conditional dynamic generation
    (context) => {
      if (process.env.NODE_ENV === 'development') {
        return ['debug-border', 'debug-grid']
      }
      return []
    }
  ]
})

Return Value Types

Safelist functions can return the following types of values:

Arrayable<string> - String or string array

safelist: [
  // Return string array
  () => ['class1', 'class2', 'class3'],

  // Return single string
  () => 'single-class',

  // Return nested array (will be flattened)
  () => [['nested1', 'nested2'], 'normal3']
]

Practical Use Cases

Dynamically Generated Class Names

When you have dynamically generated class names that might not be detected by static analysis:

safelist: [
  // Dynamic color classes
  () => {
    const dynamicColors = ['primary', 'secondary', 'accent']
    return dynamicColors.flatMap(color => [
      `bg-${color}`,
      `text-${color}`,
      `border-${color}`
    ])
  },

  // Dynamic size classes
  () => {
    return Array.from({ length: 12 }, (_, i) => `gap-${i + 1}`)
  }
]

Third-party Component Library Support

Provide necessary class names for third-party component libraries:

safelist: [
  // Reserved class names for component library
  'prose',
  'prose-sm',
  'prose-lg',

  // Dynamically generate component variants
  () => {
    const variants = ['primary', 'secondary', 'danger', 'success']
    const sizes = ['sm', 'md', 'lg']

    return variants.flatMap(variant =>
      sizes.map(size => `btn-${variant}-${size}`)
    )
  }
]

Relationship with Other Configurations

Difference from blocklist

safelist: Ensures specified class names are always included
blocklist: Ensures specified class names are always excluded

export default defineConfig({
  safelist: ['always-include'],
  blocklist: ['never-include']
})

Relationship with Generation Options

When generating CSS, you can control whether to include safelist through GenerateOptions:

const { css } = await uno.generate('', {
  safelist: true // Include class names from safelist
})