Skip to content
Search

Tailwind:Plugins

lastmod 2024-03-17created 2023-03-2510 edits

Extend Tailwind with reusable third-party plugins. ​

Overview

Plugins let you register new styles for Tailwind to inject into the user's stylesheet using JavaScript instead of CSS.

Usage

To get started with your first plugin, import the plugin function from tailwindcss/plugin.

Then, inside the array, use an anonymous function as the first argument. 

const plugin = require('tailwindcss/plugin')

module.exports = {
  plugins: [
    plugin(function({ addUtilities, addComponents, e, config }) {
      // Add your custom styles here
    }),
  ]
}

Plugin functions receive a single object argument that can be destructured into several helper functions.

  • #addUtilities - for registering new static utility styles
  • #matchUtilities - for registering new dynamic utility styles
  • #addComponents - for registering new static component styles
  • #matchComponents - for registering new dynamic component styles
  • #addBase - for registering new base styles
  • #addVariant - for registering custom static variants
  • #matchVariant - for registering custom dynamic variants
  • #theme - for looking up values in the user's theme configuration.
  • #config - for looking up values in the user's Tailwind configuration
  • #corePlugins - for checking if a core plugin is enabled
  • #e - for manually escaping strings meant to be used in class names

Official plugins

We've developed a few official plugins for popular features that for one reason or another don't belong in core yet.

You can add a plugin to your project by installing it via npm, then adding it to your file

tailwind.config.js: 

/** @type {import('tailwindcss').Config} */
module.exports = {
  // ...
  plugins: [
    require('@tailwindcss/typography'),
    require('@tailwindcss/forms'),
    require('@tailwindcss/aspect-ratio'),
    require('@tailwindcss/container-queries'),
  ]
}

Typography

The plugin can be used to quickly add sensible typographic styles to content blocks that come from sources like markdown or a CMS database. 

<article class="prose lg:prose-xl">
  <h1>Garlic bread with cheese: What the science tells us</h1>
  <p>
    For years parents have espoused the health benefits of eating garlic bread with cheese to their
    children, with the food earning such an iconic status in our culture that kids will often dress
    up as warm, cheesy loaf for Halloween.
  </p>
  <p>
    But a recent study shows that the celebrated appetizer may be linked to a series of rabies cases
    springing up around the country.
  </p>
  <!-- ... -->
</article>

Forms

Adds an opinionated form reset layer that makes it easier to style form elements. 

<!-- You can actually customize padding on a select element: -->
<select class="px-4 py-3 rounded-full">
  <!-- ... -->
</select>

<!-- Or change a checkbox color using text color utilities: -->
<input type="checkbox" class="rounded text-pink-500" />

Aspect ratio

Adds and classes that can be combined to give an element a fixed aspect ratio. 

<div class="aspect-w-16 aspect-h-9">
  <iframe src="https://www.youtube.com/embed/dQw4w9WgXcQ" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
</div>

Container queries

Lets you style an element based on the size of a marked parent element instead of the viewport. 

<div class="@container">
  <div class="@lg:text-sky-400">
    <!-- ... -->
  </div>
</div>

APIs

addUtilities

matchUtilities 

import plugin from 'tailwindcss/plugin';

/** @type {import('tailwindcss').Config} */
export default {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {
      textShadow: {
        xs: '0 1px 2px var(--tw-shadow-color)',
        sm: '0 2px 4px var(--tw-shadow-color)',
        base: '0 4px 8px var(--tw-shadow-color)',
        md: '0 8px 16px var(--tw-shadow-color)',
        lg: '0 12px 24px var(--tw-shadow-color)',
      },
    },
  },
  plugins: [
    plugin(function ({ matchUtilities, theme }) {
      matchUtilities(
        {
          'text-shadow': (value) => ({
            textShadow: value,
          }),
        },
        { values: theme('textShadow') }
      )
    }),
  ],
}

addComponents

matchComponents

addBase

addVariant

matchVariant

theme

config

corePlugins

e

Color Extend

If you use it as follows, <alpha-value> is substituted when you add an alpha value, as in @apply bg-primary/2: 

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    colors: {
      // Using modern `rgb`
      primary: 'rgb(var(--color-primary) / <alpha-value>)',
      secondary: 'rgb(var(--color-secondary) / <alpha-value>)',

      // Using modern `hsl`
      primary: 'hsl(var(--color-primary) / <alpha-value>)',
      secondary: 'hsl(var(--color-secondary) / <alpha-value>)',

      // Using legacy `rgba`
      primary: 'rgba(var(--color-primary), <alpha-value>)',
      secondary: 'rgba(var(--color-secondary), <alpha-value>)',
    }
  }
}

Problem with <alpha-value> not being applied

interestingly, theme(), "theme()" and @apply will all generate different values:

see https://play.tailwindcss.com/fX0CEoXvGu 

addUtilities({
  '.test': {
    color: theme('colors.primary.DEFAULT'),
    background: 'theme("colors.primary.DEFAULT")',
    '@apply border-primary': '',
  },
})

will generate: 

.test {
    color: rgb(var(--primary) / <alpha-value>);
    background: rgb(var(--primary) / 1);
    --tw-border-opacity: 1;
    border-color: rgb(var(--primary) / var(--tw-border-opacity));
}

looks like only @apply does the correct thing currently?

Example 

const colCount = plugin(
  function ({addUtilities, theme, e}) {
    const values = theme('colCount')
    var utilities = Object.entries(values).map(([key, value]) => {
      return {
        [`.${e(`col-count-${key}`)}`]: {columnCount: `${value}`},
      }
    })
    addUtilities(utilities)
  },
  {
    theme: {
      colCount: {
        2: '2',
        3: '3',
        4: '4',
        5: '5',
        6: '6',
      },
    },
  },
)
module.exports = colCount

Theme plugin used for scrap classification 

/** @type {import('tailwindcss/plugin').Plugin} */
const plugin = require('tailwindcss/plugin');

const rallyColors = { ... };

const rallyTheme = plugin(({theme}) => {}, {
  theme: {
    extend: {
      fontFamily: {
        sans: ['Noto Sans KR', 'sans-serif', 'system-ui'],
        serif: ['serif', 'system-ui'],
        mono: ['monospace', 'system-ui'],
      },
      colors: {
        background: '#36363F',
        foreground: '#FFFFFF',
        header: '#2b2b32',

        primary: rallyColors.green['500'],
        secondary: rallyColors.teal['700'],
        tertiary: rallyColors.orange['300'],
        quaternary: rallyColors.yellow['300'],
        quinary: rallyColors.purple['200'],
        senary: rallyColors.blue['200'],

        error: '#B00020',
        warning: '#FB8C00',
        info: '#2196F3',
        success: '#4CAF50',

        ...rallyColors,
      },
      spacing: {
        topbar: '2.5rem',
      },
    },
  },
});

module.exports = rallyTheme;

Then used in tailwind.config.js as follows: 

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['./src/**/*.{js,jsx,ts,tsx}'],
  plugins: [require('./tailwind.plugin.rally')],
};

See also

Favorite site

author Zer0 sitemap