Tailwind CSS - Functions & Directives

Directives in Tailwind CSS are commands used in your CSS to apply or customize styles.

Directives are Tailwind CSS commands you use in your CSS to access special features and control the styling applied by Tailwind CSS.

@tailwind

The @tailwind directive allows you to include Tailwind's base styles, components, utilities, and variants directly into your CSS.

Example

/**
 * Inserts Tailwind's foundational styles and any additional base styles from plugins.
 */
@tailwind base;

/**
 * Includes Tailwind's component styles and any extra component styles from plugins.
 */
@tailwind components;

/**
 * Adds Tailwind's utility classes and any additional utility classes from plugins.
 */
@tailwind utilities;

/**
 * Controls the placement of variant styles (like hover, focus, and responsive) in your CSS.
 * If not specified, these variants are added at the end of your stylesheet by default.
 */
@tailwind variants;

@layer

The @layer directive lets you specify which category (base, components, or utilities) your custom styles should belong to in Tailwind.

Example

/**
 * Import Tailwind's base styles, component styles, and utility classes into your CSS.
 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/**
 * Define custom base styles for HTML elements using the base layer.
 */
@layer base {
  h1 {
    @apply font-bold text-3xl; /* Applies a bold font and large size to h1 elements */
  }
  h2 {
    @apply font-semibold text-2xl; /* Applies a semi-bold font and medium size to h2 elements */
  }
}

/**
 * Create custom component styles using the components layer.
 */
@layer components {
  .card {
    @apply bg-gray-100 border border-gray-300 p-4 rounded-lg shadow-md; /* Styles for a card component */
  }
}

/**
 * Add custom utility classes using the utilities layer.
 */
@layer utilities {
  .no-opacity {
    opacity: 1; /* Sets the element's opacity to fully opaque */
  }
  .blurred {
    filter: blur(5px); /* Applies a blur effect to elements */
  }
}

Tailwind automatically organizes CSS within @layer directives to match the order of @tailwind rules, so you don't need to worry about order to avoid specificity issues.

Custom CSS in these layers will only be included in the final build if used in your HTML, just like default Tailwind classes.

Additionally, using @layer lets you apply modifiers like hover, focus, and responsive breakpoints like like md: and lg: to your custom styles.

@apply

@apply allows you to include existing utility classes directly into your custom CSS.

This is helpful if you want to use Tailwind's styles while writing your own CSS, making it easier to customize or override styles from other sources.

Example

.custom-card {
    @apply rounded-lg shadow-lg;
}
.custom-input {
    @apply border border-gray-400 rounded-md;
}
.custom-header {
    @apply text-xl font-semibold text-gray-800;
  }

When you use @apply, any !important declarations are removed by default to prevent conflicts with other CSS rules. Here's how it works.

Example

/* Define a class with !important */
.text-red {
  color: red !important;
}

/* Apply the .text-red class to another class */
.alert {
  @apply text-red;
}

 
/* The .text-red class retains the !important declaration */
.text-red {
  color: red !important;
}

/* The .alert class does not include !important */
.alert {
  color: red;
}

If you want to use @apply to include styles from an existing class and ensure they are !important, you need to explicitly add !important to the end of each property in your custom CSS.

    /* The .card class without !important */
.card {
  padding: 1rem;
  background-color: #edf2f7;
  border: 1px solid #cbd5e0;
  border-radius: .375rem;
}

/* The .card-important class with !important */
.card-important {
  padding: 1rem !important;
  background-color: #edf2f7 !important;
  border: 1px solid #cbd5e0 !important;
  border-radius: .375rem !important;
}

To apply !important with @apply, add !important to each property. Sass/SCSS, include !important using this approach:

/* Apply !important using Sass variable */
.card-important {
    @apply p-4 bg-gray-200 border border-gray-400 rounded;
    @apply #{$important}; /* Applies !important */
}

Using @apply with per-component CSS

In frameworks like Vue and Svelte, you can include styles directly within a <style> block inside each component file.

Trying to use a custom class from your global CSS inside a <style> block in frameworks like Vue or Svelte will cause an error because it can't find the class.

Example :main.css

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

@layer components {
    .button {
      background-color: theme('colors.blue.500');
      border-radius: theme('borderRadius.md');
      padding: theme('spacing.4');
      color: theme('colors.white');
    }
}

Example :Card.svelte

    
<button>
    <slot></slot>
</button>

<style>
    button {
        /* This won't work because Button.svelte and main.css are processed separately */
        @apply button;
    }
</style>

In this example, .button is defined in main.css, but @apply inside Button.svelte doesn't work because each file is processed separately. Vue and Svelte handle their <style> blocks independently, so they can't use styles from global CSS directly.

When you have multiple components, each with its own <style> block, Tailwind processes each file separately. For example, if you define a .button class in main.css but try to use @apply button in Button.svelte, it won't work. This is because Tailwind processes Button.svelte and main.css independently, so it doesn't recognize the .button class when used in Button.svelte.

Instead of trying to use @apply across different files, define your styles directly in Tailwind's configuration. Here's how.

Example

    
const plugin = require('tailwindcss/plugin')

module.exports = {
    // ...
    plugins: [
        plugin(function ({ addComponents, theme }) {
            addComponents({
              '.button': {
                backgroundColor: theme('colors.blue.500'),
                borderRadius: theme('borderRadius.md'),
                padding: theme('spacing.4'),
                boxShadow: theme('boxShadow.md'),
                color: theme('colors.white'),
              }
            })
        })
    ]
}

By doing this, any Tailwind CSS file will have access to the .button class.

For a smoother experience, it's better to use Tailwind's utility classes directly in your HTML instead of relying on @apply across different files. This approach simplifies your setup and avoids complications.

@config

The @config directive tells Tailwind CSS which configuration file to use when it processes a particular CSS file. This is useful if you have different config files for various parts of your project.

In site.css, you might use the default configuration.

Example

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

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

In admin.css, you can specify a different config file with:

Example

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

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

The path you specify in the @config directive is relative to the CSS file itself and will override any configurations set in your PostCSS settings or Tailwind CLI.

When using Tailwind CSS with postcss-import, make sure that all your @import statements come before the @config directive in your CSS file.

Why? postcss-import needs to process @import statements first, following CSS rules that require imports to appear before any other rules. If you place @config before your @import statements, it will cause issues, and your styles might not be processed correctly.

Example: Incorrect Order

/* Incorrect order - will cause problems */
@config "./tailwind.admin.config.js";

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

Example :Correct Order

/* Always put @import first */
@import "tailwindcss/base";
@import "./custom-base.css";
@import "tailwindcss/components";
@import "./custom-components.css";
@import "tailwindcss/utilities";

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

Functions

With Tailwind, you can use custom functions in your CSS to access Tailwind-specific values. These functions are calculated at build time and are converted into static values in the final CSS.

@theme

To access values from your Tailwind config, simply use the theme() function with dot notation.

Example

.button {
  border-width: theme(borderWidth.md);
}

If you need to use values with dots (like 3.5 in the border width scale), apply square brackets:

Example

.button {
  border-width: theme(borderWidth[3.5]);
}

To access nested colors in Tailwind's default color palette, use dot notation to ensure proper referencing of the color values.

Avoid using dashes for nested color values.

Example

    /* Incorrect */
.button {
    background-color: theme(colors.green-500);
}

Use dots to access nested color values.

Example

   /* Correct */
.button {
    background-color: theme(colors.green.500);
} 

To change the opacity of a theme color, add a slash followed by the opacity percentage:

Example

.card-bg {
    background-color: theme(colors.green.300 / 50%);
}

@screens

The screen() function in Tailwind CSS lets you create media queries using named breakpoints, avoiding the need to repeat values in your CSS.

Example

@media screen(md) {
    /* Styles for medium screens and up */
}

This will be converted into a standard media query for the specified breakpoint when your CSS is built.

Example

@media (min-width: 768px) {
    /* Styles for screens that are at least 768px wide */
}

@screens

The screen() function in Tailwind CSS helps you create media queries using named breakpoints instead of repeating their values in your CSS.

Example

@media screen(md) {
    /* Styles for medium screens and up */
}

This will be converted into a standard media query for the specified breakpoint when your CSS is built.

Example

@media (min-width: 768px) {
    /* Styles for screens that are at least 768px wide */
}