Question

A reference for the custom functions and directives Tailwind exposes to your CSS.

Directives

Directives are custom Tailwind-specific at-rules you can use in your CSS that offer special functionality for Tailwind CSS projects.

@tailwind

Use the @tailwind directive to insert Tailwind’s base, components, utilities and variants styles into your CSS.

/**
 * This injects Tailwind's base styles and any base styles registered by
 * plugins.
 */
@tailwind base;

/**
 * This injects Tailwind's component classes and any component classes
 * registered by plugins.
 */
@tailwind components;

/**
 * This injects Tailwind's utility classes and any utility classes registered
 * by plugins.
 */
@tailwind utilities;

/**
 * Use this directive to control where Tailwind injects the hover, focus,
 * responsive, dark mode, and other variants of each class.
 *
 * If omitted, Tailwind will append these classes to the very end of
 * your stylesheet by default.
 */
@tailwind variants;

@layer

Use the @layer directive to tell Tailwind which “bucket” a set of custom styles belong to. Valid layers are base, components, and utilities.

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  h1 {
    @apply text-2xl;
  }
  h2 {
    @apply text-xl;
  }
}

@layer components {
  .btn-blue {
    @apply bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded;
  }
}

@layer utilities {
  .filter-none {
    filter: none;
  }
  .filter-grayscale {
    filter: grayscale(100%);
  }
}

Tailwind will automatically move the CSS within any @layer directive to the same place as the corresponding @tailwind rule, so you don’t have to worry about authoring your CSS in a specific order to avoid specificity issues.

Any custom CSS added to a layer will only be included in the final build if that CSS is actually used in your HTML, just like all of the classes built in to Tailwind by default.

Wrapping any custom CSS with @layer also makes it possible to use modifiers with those rules, like hover: and focus: or responsive modifiers like md: and lg:.

@apply

Use @apply to inline any existing utility classes into your own custom CSS.

This is useful when you need to write custom CSS (like to override the styles in a third-party library) but still want to work with your design tokens and use the same syntax you’re used to using in your HTML.

.select2-dropdown {
  @apply rounded-b-lg shadow-md;
}
.select2-search {
  @apply border border-gray-300 rounded;
}
.select2-results__group {
  @apply text-lg font-bold text-gray-900;
}

Any rules inlined with @apply will have !important removed by default to avoid specificity issues:

/* Input */
.foo {
  color: blue !important;
}

.bar {
  @apply foo;
}

/* Output */
.foo {
  color: blue !important;
}

.bar {
  color: blue;
}

If you’d like to @apply an existing class and make it !important, simply add !important to the end of the declaration:

/* Input */
.btn {
  @apply font-bold py-2 px-4 rounded !important;
}

/* Output */
.btn {
  font-weight: 700 !important;
  padding-top: .5rem !important;
  padding-bottom: .5rem !important;
  padding-right: 1rem !important;
  padding-left: 1rem !important;
  border-radius: .25rem !important;
}

Note that if you’re using Sass/SCSS, you’ll need to use Sass’ interpolation feature to get this to work:

.btn {
  @apply font-bold py-2 px-4 rounded #{!important};
}

Using @apply with per-component CSS

Component frameworks like Vue and Svelte support adding per-component styles within a <style> block that lives in each component file.

If you try to @apply a custom class you’ve defined in your global CSS in one of these per-component <style> blocks, you’ll get an error about the class not existing:

main.css

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer components {
  .card {
    background-color: theme(colors.white);
    border-radius: theme(borderRadius.lg);
    padding: theme(spacing.6);
    box-shadow: theme(boxShadow.xl);
  }
}

Card.svelte

<div>
  <slot></slot>
</div>

<style>
  div {
    /* Won't work because this file and main.css are processed separately */
    @apply card;
  }
</style>

This is because under-the-hood, frameworks like Vue and Svelte are processing every single <style> block independently, and running your PostCSS plugin chain against each one in isolation.

That means if you have 10 components that each have a <style> block, Tailwind is being run 10 separate times, and each run has zero knowledge about the other runs. Because of this, when you try to @apply card in Card.svelte it fails, because Tailwind has no idea that the card class exists since Svelte processed Card.svelte and main.css in total isolation from each other.

The solution to this problem is to define any custom styles you want to @apply in your components using the plugin system instead:

tailwind.config.js

const plugin = require('tailwindcss/plugin')

module.exports = {
  // ...
  plugins: [
    plugin(function ({ addComponents, theme }) {
      addComponents({
        '.card': {
          backgroundColor: theme('colors.white'),
          borderRadius: theme('borderRadius.lg'),
          padding: theme('spacing.6'),
          boxShadow: theme('boxShadow.xl'),
        }
      })
    })
  ]
}

This way any file processed by Tailwind that uses this config file will have access to those styles.

Honestly though the best solution is to just not do weird stuff like this at all. Use Tailwind’s utilities directly in your markup the way they are intended to be used, and don’t abuse the @apply feature to do things like this and you will have a much better experience.

@config

Use the @config directive to specify which config file Tailwind should use when compiling that CSS file. This is useful for projects that need to use different configuration files for different CSS entry points.

@config "./tailwind.site.config.js";

@tailwind base;
@tailwind components;
@tailwind utilities;

The path you provide to the @config directive is relative to that CSS file, and will take precedence over a path defined in your PostCSS configuration or in the Tailwind CLI.

Note that if you’re using postcss-import, your @import statements need to come before @config for things to work correctly, as postcss-import is strict about following the CSS spec which requires @import statements to precede any other rules in the file.

Don’t put @config before your @import statements

admin.css

@config "./tailwind.admin.config.js";

@import "tailwindcss/base";
@import "./custom-base.css";
@import "tailwindcss/components";
@import "./custom-components.css";
@import "tailwindcss/utilities";

Put your @import statements before the @config directive

admin.css

@import "tailwindcss/base";
@import "./custom-base.css";
@import "tailwindcss/components";
@import "./custom-components.css";
@import "tailwindcss/utilities";

@config "./tailwind.admin.config.js";

---

Functions

Tailwind adds a few custom functions you can use in your CSS to access Tailwind-specific values. These functions are evaluated at build-time, and are replaced by static values in your final CSS.

theme()

Use the theme() function to access your Tailwind config values using dot notation.

.content-area {
  height: calc(100vh - theme(spacing.12));
}

If you need to access a value that contains a dot (like the 2.5 value in the spacing scale), you can use square bracket notation:

.content-area {
  height: calc(100vh - theme(spacing[2.5]));
}

Since Tailwind uses a nested object syntax to define its default color palette, make sure to use dot notation to access the nested colors.

Don’t use the dash syntax when accessing nested color values

.btn-blue {
  background-color: theme(colors.blue-500);
}

Use dot notation to access nested color values

.btn-blue {
  background-color: theme(colors.blue.500);
}

To adjust the opacity of a color retrieved with theme, use a slash followed by the opacity value you want to use:

.btn-blue {
  background-color: theme(colors.blue.500 / 75%);
}

screen()

The screen function allows you to create media queries that reference your breakpoints by name instead of duplicating their values in your own CSS.

@media screen(sm) {
  /* ... */
}

This will resolve to the underlying screen value at build-time, generating a regular media query that matches specified breakpoint:

@media (min-width: 640px) {
  /* ... */
}