Directives in Tailwind CSS v4: A Complete Guide

Tailwind CSS v4 introduces a modern approach to configuration and styling. One of the most important changes is the enhanced directive system, which allows developers to define themes, utilities, and variants directly within CSS.

What Are Directives?

Directives are special instructions processed by Tailwind CSS. They provide powerful ways to import the framework, define design tokens, create custom utilities, and manage variants.

Key Directives in Tailwind CSS v4

1. @import

In Tailwind CSS v4, importing the framework is much simpler:

@import "tailwindcss";

This single line loads the entire Tailwind framework into your project.

2. @theme

The @theme directive is used to define design tokens such as colors, spacing values, and typography settings.

@theme {
  --color-primary: #3b82f6;
  --color-secondary: #8b5cf6;
}

These variables can be reused throughout your application.

3. @utility

The @utility directive allows developers to create custom utility classes.

@utility flex-center {
  display: flex;
  align-items: center;
  justify-content: center;
}

This creates a reusable utility class named flex-center.

4. @variant

The @variant directive applies styles to specific states such as hover, focus, or dark mode.

.button {
  @variant hover {
    opacity: 0.8;
  }
}

5. @custom-variant

Developers can define custom variants for advanced styling scenarios.

@custom-variant theme-dark (&:where(.dark *));

This is particularly useful for custom theme implementations.

Benefits of Tailwind CSS v4 Directives

• Cleaner project structure
• Improved design token management
• Less reliance on JavaScript configuration
• Easier custom utility creation
• Better scalability and maintainability

Tailwind CSS v4 vs Previous Versions

Previous versions relied on multiple directives:

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

In v4, this is simplified to:

@import "tailwindcss";

This change reduces complexity and streamlines project setup.

Conclusion

The new directive system in Tailwind CSS v4 offers a more powerful and intuitive way to manage styles. By mastering directives such as @theme, @utility, @variant, and @custom-variant, developers can build scalable, maintainable, and modern design systems more efficiently.