Skip to main content

​
Introduction

The Tailwind CSS plugin system allows you to extend the framework with custom utilities, variants, components, and base styles. Plugins receive a PluginAPI object with methods to register new styles and access theme configuration.

​
plugin() Function

Create a plugin by calling the default export from tailwindcss/plugin.
​
handler
(api: PluginAPI) => void
required
Function that receives the Plugin API and registers custom styles
​
config
Partial<Config>
Optional configuration object to extend theme values or add variants

​
Basic Plugin

import plugin from 'tailwindcss/plugin'

export default plugin(function({ addUtilities }) {
  addUtilities({
    '.scrollbar-none': {
      'scrollbar-width': 'none',
      '&::-webkit-scrollbar': {
        display: 'none'
      }
    }
  })
})

​
Plugin with Configuration

import plugin from 'tailwindcss/plugin'

export default plugin(function({ addBase }) {
  addBase({
    body: {
      margin: '0'
    }
  })
}, {
  theme: {
    extend: {
      colors: {
        'brand-blue': '#1fb6ff'
      }
    }
  }
})

​
plugin.withOptions()

Create a plugin that accepts configuration options.
​
pluginFunction
(options?: T) => PluginFn
required
Function that returns a plugin handler based on the provided options
​
configFunction
(options?: T) => Partial<Config>
Optional function that returns configuration based on the provided options

​
Example

import plugin from 'tailwindcss/plugin'

export default plugin.withOptions(
  function(options = { className: 'scrollbar-none' }) {
    return function({ addUtilities }) {
      addUtilities({
        [`.${options.className}`]: {
          'scrollbar-width': 'none'
        }
      })
    }
  },
  function(options = {}) {
    return {
      theme: {
        extend: {
          colors: options.colors || {}
        }
      }
    }
  }
)

​
PluginAPI Interface

The Plugin API provides methods to extend Tailwind CSS:
MethodDescription
addUtilities()Register static utility classes
matchUtilities()Register dynamic utilities that accept values
addVariant()Register a static variant
matchVariant()Register a dynamic variant that accepts values
addBase()Add base styles to the @layer base
addComponents()Add component styles (alias for addUtilities)
theme()Access theme configuration values
config()Access arbitrary configuration values
prefix()Apply the configured prefix to a class name

​
CssInJs Type

Plugins use a CSS-in-JS object format to define styles: 
type CssInJs = {
  [key: string]: string | string[] | CssInJs | CssInJs[]
}

​
Features

  • Nested selectors: Use & for the current selector
  • Pseudo-classes: Define :hover, :focus, etc. as nested objects
  • Media queries: Use @media as object keys
  • At-rules: Support for @supports, @keyframes, etc.
  • camelCase properties: Automatically converted to kebab-case
  • Arrays: Multiple values for the same property

​
Example

{
  '.custom-utility': {
    display: 'flex',
    flexDirection: 'column',
    '&:hover': {
      opacity: '0.8'
    },
    '@media (min-width: 768px)': {
      flexDirection: 'row'
    }
  }
}

​
Loading Plugins

​
In CSS Files

@plugin "./plugins/my-plugin.js";

​
In Configuration Files

import myPlugin from './plugins/my-plugin'

export default {
  plugins: [
    myPlugin,
    myPlugin({ option: 'value' }) // For plugins with options
  ]
}

​
Type Exports

import type {
  Config,
  PluginAPI,
  PluginCreator,
  PluginsConfig,
  PluginUtils,
  ThemeConfig
} from 'tailwindcss/plugin'
Plugin handlers are called during build time. Use the design system API to register utilities and variants that are generated on demand.

Build docs developers (and LLMs) love

Get started for freeTalk to us