Skip to main content

​
theme()

Access theme configuration values from both CSS @theme declarations and JavaScript config.
​
path
string
required
Dot-notation path to the theme value (e.g., 'colors.blue.500', 'spacing.4')
​
defaultValue
any
Fallback value if the path doesn’t exist

​
Basic Usage

import plugin from 'tailwindcss/plugin'

export default plugin(function({ addUtilities, theme }) {
  addUtilities({
    '.custom': {
      color: theme('colors.blue.500'),
      padding: theme('spacing.4'),
      borderRadius: theme('borderRadius.lg')
    }
  })
})

​
With Default Value

const customColor = theme('colors.brand.primary', '#3b82f6')

​
Nested Properties

const colors = theme('colors')
// Returns all color values as an object

const spacing = theme('spacing')
// Returns all spacing values

const fontSize = theme('fontSize.xl')
// Returns the xl font size value

​
Using in matchUtilities

import plugin from 'tailwindcss/plugin'

export default plugin(function({ matchUtilities, theme }) {
  matchUtilities(
    {
      'text-shadow': (value) => ({
        'text-shadow': value
      })
    },
    {
      values: theme('boxShadow')
    }
  )
})

​
Extending Theme Colors

import plugin from 'tailwindcss/plugin'

export default plugin(
  function({ matchUtilities, theme }) {
    matchUtilities(
      {
        scrollbar: (value) => ({
          'scrollbar-color': value
        })
      },
      {
        type: 'color',
        values: theme('colors')
      }
    )
  },
  {
    theme: {
      extend: {
        colors: {
          'brand': '#1fb6ff'
        }
      }
    }
  }
)

<div class="scrollbar-brand">
<div class="scrollbar-blue-500">

​
Opacity Modifiers

Theme colors support opacity modifiers using the / syntax: 
import plugin from 'tailwindcss/plugin'

export default plugin(function({ addUtilities, theme }) {
  addUtilities({
    '.percentage': {
      color: theme('colors.red.500 / 50%')
    },
    '.fraction': {
      color: theme('colors.red.500 / 0.5')
    },
    '.variable': {
      color: theme('colors.red.500 / var(--opacity)')
    }
  })
})
Compiles to: 
.percentage {
  color: color-mix(in oklab, #ef4444 50%, transparent);
}

.fraction {
  color: color-mix(in oklab, #ef4444 50%, transparent);
}

.variable {
  color: #ef4444;
}
@supports (color: color-mix(in lab, red, red)) {
  .variable {
    color: color-mix(in oklab, #ef4444 var(--opacity), transparent);
  }
}

​
Theme Value Resolution

The theme() function merges values from multiple sources:
  1. CSS theme values from @theme declarations (highest priority)
  2. Plugin config from the config parameter
  3. Global config from configuration files
  4. Default theme values
import plugin from 'tailwindcss/plugin'

export default plugin(
  function({ addUtilities, theme }) {
    addUtilities({
      '.custom': {
        // This will use the value from plugin config if present,
        // otherwise falls back to global config or defaults
        color: theme('colors.primary', '#000000')
      }
    })
  },
  {
    theme: {
      extend: {
        colors: {
          primary: '#1fb6ff'
        }
      }
    }
  }
)

​
Referencing Other Theme Values

Theme functions can reference other theme keys: 
import plugin from 'tailwindcss/plugin'

export default plugin(
  function({ matchUtilities, theme }) {
    matchUtilities(
      {
        'animate-delay': (value) => ({
          'animation-delay': value
        })
      },
      {
        values: theme('transitionDuration')
      }
    )
  },
  {
    theme: {
      extend: {
        // Reference built-in theme values
        animationDuration: ({ theme }) => ({
          ...theme('transitionDuration')
        }),
        animationDelay: ({ theme }) => ({
          ...theme('animationDuration')
        })
      }
    }
  }
)

​
Common Theme Paths

PathDescriptionExample
colorsColor palettecolors.blue.500
spacingSpacing scalespacing.4
fontSizeFont sizesfontSize.xl
fontFamilyFont familiesfontFamily.sans
fontWeightFont weightsfontWeight.bold
lineHeightLine heightslineHeight.tight
letterSpacingLetter spacingletterSpacing.wide
borderRadiusBorder radiiborderRadius.lg
borderWidthBorder widthsborderWidth.2
boxShadowBox shadowsboxShadow.xl
screensBreakpointsscreens.md
transitionDurationDurationstransitionDuration.300
transitionTimingFunctionEasing functionstransitionTimingFunction.ease-in-out
zIndexZ-index valueszIndex.50
opacityOpacity valuesopacity.50

​
config()

Access raw configuration values outside of the theme.
​
path
string
Dot-notation path to the config value (e.g., 'prefix', 'important'). Omit to get the entire config.
​
defaultValue
any
Fallback value if the path doesn’t exist

​
Get Entire Config

import plugin from 'tailwindcss/plugin'

export default plugin(function({ config }) {
  const fullConfig = config()
  console.log(fullConfig)
})

​
Access Specific Values

import plugin from 'tailwindcss/plugin'

export default plugin(function({ config }) {
  const prefix = config('prefix', '')
  const important = config('important', false)
  const darkMode = config('darkMode', 'media')
  
  console.log({ prefix, important, darkMode })
})

​
Custom Config Options

import plugin from 'tailwindcss/plugin'

export default plugin(function({ addUtilities, config }) {
  const customOption = config('myPlugin.enabled', true)
  
  if (customOption) {
    addUtilities({
      '.custom': {
        display: 'block'
      }
    })
  }
})
Usage: 
// tailwind.config.js
export default {
  myPlugin: {
    enabled: true
  },
  plugins: [
    require('./my-plugin')
  ]
}

​
prefix()

Apply the configured prefix to a class name.
​
className
string
required
The class name to prefix

​
Example

import plugin from 'tailwindcss/plugin'

export default plugin(function({ addUtilities, prefix }) {
  addUtilities({
    [`.${prefix('custom-utility')}`]: {
      display: 'flex'
    }
  })
})
With prefix: 'tw-' configuration: 
.tw-custom-utility {
  display: flex;
}
In v4, the prefix() function is primarily for compatibility. The design system automatically handles prefixing for utilities registered through the Plugin API.

​
Bare Value Support

Many theme keys support bare values (numeric values without explicit units): 
import plugin from 'tailwindcss/plugin'

export default plugin(function({ matchUtilities, theme }) {
  matchUtilities(
    {
      'animate-duration': (value) => ({
        'animation-duration': value
      })
    },
    {
      values: theme('transitionDuration')
    }
  )
})

<!-- Named value -->
<div class="animate-duration-300">

<!-- Bare value (automatically converts to 316ms) -->
<div class="animate-duration-316">

<!-- Arbitrary value -->
<div class="animate-duration-[2s]">

​
DEFAULT Key

The DEFAULT key in theme objects maps to utilities without a suffix: 
import plugin from 'tailwindcss/plugin'

export default plugin(
  function({ matchUtilities, theme }) {
    matchUtilities(
      {
        'text-shadow': (value) => ({
          'text-shadow': value
        })
      },
      {
        values: theme('textShadow')
      }
    )
  },
  {
    theme: {
      extend: {
        textShadow: {
          sm: '0 1px 2px rgba(0, 0, 0, 0.05)',
          DEFAULT: '0 2px 4px rgba(0, 0, 0, 0.1)',
          lg: '0 8px 16px rgba(0, 0, 0, 0.15)'
        }
      }
    }
  }
)

<div class="text-shadow"><!-- Uses DEFAULT value -->
<div class="text-shadow-sm">
<div class="text-shadow-lg">

​
CSS Variable Access

Access CSS custom properties directly: 
const value = theme('--color-primary')
// Returns the value of --color-primary from @theme
The theme() function intelligently merges CSS @theme values with JavaScript config, prioritizing CSS values for better performance and CSS-first workflows in v4.

Build docs developers (and LLMs) love

Get started for freeTalk to us