Skip to main content

​
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

​
presets
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')
  ]
}
​
theme
ThemeConfig
Theme configuration for customizing design tokens.
theme: {
  colors: {
    primary: '#3b82f6',
    secondary: '#8b5cf6'
  },
  extend: {
    spacing: {
      '128': '32rem'
    }
  }
}
​
plugins
Plugin[]
Array of plugins to extend Tailwind’s functionality.
import customPlugin from './custom-plugin'

const config: UserConfig = {
  plugins: [
    customPlugin,
    require('@tailwindcss/typography')
  ]
}
​
content
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']
}
​
darkMode
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"] *)']]
​
prefix
string
Prefix to add to all utility class names.
prefix: 'tw-'
// Generates: tw-flex, tw-bg-blue-500, etc.
​
blocklist
string[]
Array of class names to exclude from generation.
blocklist: [
  'container',
  'collapse'
]
​
important
boolean | string
Make all utilities !important or scope them to a selector.
// All utilities are !important
important: true

// Scope utilities to #app
important: '#app'
​
future
'all' | Record<string, boolean>
Enable future opt-in features.
future: {
  hoverOnlyWhenSupported: true
}

// Or enable all future features
future: 'all'
​
experimental
'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

​
theme
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',
    // ...
  }
}
​
plugins
PluginWithConfig[]
Array of resolved plugins with their configuration.
​
content
ResolvedContentConfig
Resolved content configuration.
interface ResolvedContentConfig {
  files: ResolvedContent[]
}

type ResolvedContent = 
  | { base: string; pattern: string }
  | { raw: string; extension?: string }
​
darkMode
DarkModeStrategy | null
Resolved dark mode strategy, or null if disabled.
​
prefix
string
Resolved prefix (empty string if none).
​
blocklist
string[]
Resolved blocklist (empty array if none).
​
important
boolean | string
Resolved important setting.
​
future
Record<string, boolean>
Resolved future flags.
​
experimental
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:
  1. Static objects - Direct key-value pairs
  2. Functions - Receive PluginUtils and return values
  3. 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'
    }
  }
}

​
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'
  ]
}

​
Complete Configuration Example

import type { Config } from 'tailwindcss'

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

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.

Build docs developers (and LLMs) love

Get started for freeTalk to us