Config Types and Configuration API

Overview

Tailwind CSS v4 provides TypeScript-first configuration types for defining themes, plugins, and content sources. The configuration system supports both user-provided configs and fully resolved configs.

import type { Config } from 'tailwindcss'

const config: Config = {
  theme: {
    extend: {
      colors: {
        primary: '#3b82f6'
      }
    }
  },
  plugins: []
}

UserConfig

The UserConfig interface defines the structure for user-provided configuration.

interface UserConfig {
  presets?: UserConfig[]
  theme?: ThemeConfig
  plugins?: Plugin[]
  content?: ContentFile[] | { relative?: boolean; files: ContentFile[] }
  darkMode?: DarkModeStrategy
  prefix?: string
  blocklist?: string[]
  important?: boolean | string
  future?: 'all' | Record<string, boolean>
  experimental?: 'all' | Record<string, boolean>
}

Properties

UserConfig[]

Array of preset configurations to extend. Presets are merged in order, with later configs taking precedence.

const config: UserConfig = {
  presets: [
    require('./preset-base'),
    require('./preset-extended')
  ]
}

ThemeConfig

Theme configuration for customizing design tokens.

Show ThemeConfig structure

type ThemeConfig = Record<string, ThemeValue> & {
  extend?: Record<string, ThemeValue>
}

type ThemeValue = 
  | ResolvableTo<Record<string, unknown>> 
  | null 
  | undefined

type ResolvableTo<T> = T | ((utils: PluginUtils) => T)

theme: {
  colors: {
    primary: '#3b82f6',
    secondary: '#8b5cf6'
  },
  extend: {
    spacing: {
      '128': '32rem'
    }
  }
}

Plugin[]

Array of plugins to extend Tailwind’s functionality.

import customPlugin from './custom-plugin'

const config: UserConfig = {
  plugins: [
    customPlugin,
    require('@tailwindcss/typography')
  ]
}

ContentFile[] | ContentConfig

Content source configuration for scanning template files.Can be either:

Simple array of file patterns or raw content
Object with relative flag and files array

// Simple array
content: [
  './src/**/*.{html,js,tsx}',
  { raw: '<div class="flex"></div>', extension: 'html' }
]

// With relative flag
content: {
  relative: true,
  files: ['./components/**/*.tsx']
}

Show ContentFile type

type ContentFile = 
  | string 
  | { raw: string; extension?: string }

DarkModeStrategy

Strategy for handling dark mode variants.Options:

false - Disable dark mode
'media' - Use prefers-color-scheme media query
'class' - Require .dark class on HTML element
['class', '.dark-theme'] - Custom dark mode class
'selector' - Use :where(.dark) selector
['selector', '[data-theme="dark"]'] - Custom selector
['variant', '&:is(.dark *)'] - Fully custom variant

// Use media query strategy
darkMode: 'media'

// Use custom class
darkMode: ['class', '.dark-theme']

// Use custom selector
darkMode: ['selector', '[data-theme="dark"]']

// Fully custom variant
darkMode: ['variant', ['&:is(.dark *)', '&:is([data-theme="dark"] *)']]

string

Prefix to add to all utility class names.

prefix: 'tw-'
// Generates: tw-flex, tw-bg-blue-500, etc.

string[]

Array of class names to exclude from generation.

blocklist: [
  'container',
  'collapse'
]

boolean | string

Make all utilities !important or scope them to a selector.

// All utilities are !important
important: true

// Scope utilities to #app
important: '#app'

'all' | Record<string, boolean>

Enable future opt-in features.

future: {
  hoverOnlyWhenSupported: true
}

// Or enable all future features
future: 'all'

'all' | Record<string, boolean>

Enable experimental features.

experimental: {
  optimizeUniversalDefaults: true
}

ResolvedConfig

The ResolvedConfig interface represents a fully processed configuration after merging presets and resolving all values.

interface ResolvedConfig {
  theme: Record<string, Record<string, unknown>>
  plugins: PluginWithConfig[]
  content: ResolvedContentConfig
  darkMode: DarkModeStrategy | null
  prefix: string
  blocklist: string[]
  important: boolean | string
  future: Record<string, boolean>
  experimental: Record<string, boolean>
}

Properties

Record<string, Record<string, unknown>>

Fully resolved theme with all presets merged and functions evaluated.

{
  colors: {
    primary: '#3b82f6',
    secondary: '#8b5cf6'
  },
  spacing: {
    '1': '0.25rem',
    '2': '0.5rem',
    // ...
  }
}

PluginWithConfig[]

Array of resolved plugins with their configuration.

ResolvedContentConfig

Resolved content configuration.

interface ResolvedContentConfig {
  files: ResolvedContent[]
}

type ResolvedContent = 
  | { base: string; pattern: string }
  | { raw: string; extension?: string }

DarkModeStrategy | null

Resolved dark mode strategy, or null if disabled.

string

Resolved prefix (empty string if none).

string[]

Resolved blocklist (empty array if none).

boolean | string

Resolved important setting.

Record<string, boolean>

Resolved future flags.

Record<string, boolean>

Resolved experimental flags.

ThemeConfig

Detailed structure for theme configuration.

type ThemeConfig = Record<string, ThemeValue> & {
  extend?: Record<string, ThemeValue>
}

type ThemeValue = ResolvableTo<Record<string, unknown>> | null | undefined

type ResolvableTo<T> = T | ((utils: PluginUtils) => T)

Theme Values

Theme values can be:

Static objects - Direct key-value pairs
Functions - Receive PluginUtils and return values
null/undefined - Disable a theme section

const config: UserConfig = {
  theme: {
    colors: {
      primary: '#3b82f6',
      secondary: '#8b5cf6',
      accent: '#ec4899'
    },
    spacing: {
      'xs': '0.5rem',
      'sm': '1rem',
      'md': '1.5rem',
      'lg': '2rem',
      'xl': '3rem'
    }
  }
}

const config: UserConfig = {
  theme: {
    colors: ({ theme }) => ({
      // Reference other theme values
      primary: theme('colors.blue.500'),
      // Computed values
      secondary: computeColor('#8b5cf6')
    }),
    
    spacing: ({ theme }) => {
      const base = 0.25 // 4px
      return {
        ...theme('spacing'),
        'custom': `${base * 10}rem`
      }
    }
  }
}

const config: UserConfig = {
  theme: {
    // Replace default colors entirely
    colors: {
      primary: '#3b82f6',
      secondary: '#8b5cf6'
    },
    
    extend: {
      // Add to default spacing without replacing
      spacing: {
        '128': '32rem',
        '144': '36rem'
      },
      
      // Add custom theme sections
      animation: {
        'spin-slow': 'spin 3s linear infinite'
      }
    }
  }
}

const config: UserConfig = {
  theme: {
    // Disable container utilities
    container: null,
    
    extend: {
      colors: {
        primary: '#3b82f6'
      }
    }
  }
}

Content Configuration

Detailed content source configuration options.

ContentFile Types

const config: UserConfig = {
  content: [
    // Glob patterns
    './src/**/*.{html,js,ts,jsx,tsx}',
    './components/**/*.vue',
    './pages/**/*.{js,ts,jsx,tsx}',
    
    // Specific files
    './index.html',
    './app.js'
  ]
}

const config: UserConfig = {
  content: [
    './src/**/*.tsx',
    
    // Inline HTML content
    {
      raw: '<div class="flex justify-center"></div>',
      extension: 'html'
    },
    
    // Inline with different extension
    {
      raw: 'const classes = "bg-blue-500 text-white"',
      extension: 'js'
    }
  ]
}

const config: UserConfig = {
  content: {
    relative: true,
    files: [
      './components/**/*.tsx',
      './pages/**/*.tsx'
    ]
  }
}

Complete Configuration Example

import type { Config } from 'tailwindcss'

const config: Config = {
  content: ['./src/**/*.{html,js,tsx}'],
  theme: {
    extend: {
      colors: {
        primary: '#3b82f6'
      }
    }
  }
}

export default config

import type { Config } from 'tailwindcss'
import customPlugin from './plugins/custom'

const config: Config = {
  // Content sources
  content: {
    relative: true,
    files: [
      './src/**/*.{html,js,ts,jsx,tsx}',
      './components/**/*.vue'
    ]
  },
  
  // Theme customization
  theme: {
    // Override defaults
    colors: {
      primary: '#3b82f6',
      secondary: '#8b5cf6',
      accent: '#ec4899'
    },
    
    // Extend defaults
    extend: {
      spacing: {
        '128': '32rem',
        '144': '36rem'
      },
      
      fontFamily: {
        sans: ['Inter', 'system-ui', 'sans-serif']
      },
      
      animation: {
        'spin-slow': 'spin 3s linear infinite',
        'bounce-slow': 'bounce 2s infinite'
      },
      
      keyframes: {
        wiggle: {
          '0%, 100%': { transform: 'rotate(-3deg)' },
          '50%': { transform: 'rotate(3deg)' }
        }
      }
    }
  },
  
  // Plugins
  plugins: [
    customPlugin,
    require('@tailwindcss/typography'),
    require('@tailwindcss/forms')
  ],
  
  // Dark mode
  darkMode: ['class', '.dark-mode'],
  
  // Prefix
  prefix: 'tw-',
  
  // Blocklist
  blocklist: ['container', 'collapse'],
  
  // Important
  important: '#app',
  
  // Future flags
  future: {
    hoverOnlyWhenSupported: true
  },
  
  // Experimental flags
  experimental: {
    optimizeUniversalDefaults: true
  }
}

export default config

import type { Config } from 'tailwindcss'
import basePreset from './presets/base'
import brandPreset from './presets/brand'

const config: Config = {
  presets: [
    basePreset,
    brandPreset
  ],
  
  content: ['./src/**/*.tsx'],
  
  theme: {
    extend: {
      // Override preset values
      colors: {
        primary: '#custom-color'
      }
    }
  }
}

export default config

import type { Config } from 'tailwindcss'

const config: Config = {
  content: ['./src/**/*.tsx'],
  
  theme: {
    colors: ({ theme }) => ({
      ...theme('colors'),
      primary: theme('colors.blue.500'),
      secondary: theme('colors.purple.500')
    }),
    
    spacing: ({ theme }) => {
      const base = theme('spacing')
      
      return {
        ...base,
        // Add fractional spacing
        '1/2': '0.125rem',
        '3/2': '0.375rem'
      }
    }
  }
}

export default config

Type Exports

import type {
  Config,              // Alias for UserConfig
  UserConfig,          // User-provided config
  ResolvedConfig,      // Fully resolved config
  ThemeConfig,         // Theme configuration
  ThemeValue,          // Theme value types
  ResolvableTo,        // Function or static value
  ResolvedThemeValue,  // Resolved theme value
} from 'tailwindcss'

v3 Compatibility Exports

For backwards compatibility with Tailwind CSS v3, the following exports are available:

Colors

Access the default color palette:

import colors from 'tailwindcss/colors'

console.log(colors.blue[500]) // '#3b82f6'
console.log(colors.red) // { 50: '#fef2f2', 100: '#fee2e2', ... }

Default Theme

Access default theme values for use in JavaScript configs:

import defaultTheme from 'tailwindcss/defaultTheme'

export default {
  theme: {
    extend: {
      fontFamily: {
        sans: ['Inter', ...defaultTheme.fontFamily.sans],
      },
    },
  },
}

Flatten Color Palette

Utility function to flatten nested color objects:

import flattenColorPalette from 'tailwindcss/lib/util/flattenColorPalette'

const colors = {
  blue: {
    500: '#3b82f6',
    600: '#2563eb',
  },
}

const flattened = flattenColorPalette(colors)
// { 'blue-500': '#3b82f6', 'blue-600': '#2563eb' }

These exports are provided for v3 compatibility. In v4, prefer using the CSS-based theme system with @theme directive and theme variables.

JavaScript API

Plugin API

CSS Features

Build Plugins

Config Types and Configuration API

Overview

UserConfig

Properties

ResolvedConfig

Properties

ThemeConfig

Theme Values

Content Configuration

ContentFile Types

Complete Configuration Example

Type Exports

v3 Compatibility Exports

Colors

Default Theme

Flatten Color Palette

​Overview

​UserConfig

​Properties

​ResolvedConfig

​Properties

​ThemeConfig

​Theme Values

​Content Configuration

​ContentFile Types

​Complete Configuration Example

​Type Exports

​v3 Compatibility Exports

​Colors

​Default Theme

​Flatten Color Palette

Overview

UserConfig

Properties

ResolvedConfig

Properties

ThemeConfig

Theme Values

Content Configuration

ContentFile Types

Complete Configuration Example

Type Exports

v3 Compatibility Exports

Colors

Default Theme

Flatten Color Palette