Tailwind CSS Directives — @apply, @layer, @config, and @theme

In this tutorial, you will learn about Tailwind CSS Directives. We cover key concepts, practical examples, and best practices to help you master this topic.

Tailwind CSS directives are special at-rules used in CSS files: @apply composes utilities, @layer controls output order, @config specifies the config file path, and @theme references design tokens.

What You'll Learn

You will learn how to use @apply to create utility-composed component classes, organize styles with @layer, reference the config with @theme, and apply best practices for each directive.

Why It Matters

Directives bridge the gap between Tailwind utilities and traditional CSS. DodaTech uses @apply sparingly for third-party overrides and @layer for proper style cascading in custom CSS files.

Real-World Use

Doda Browser uses @apply in a few component CSS files for rich text editor styles, where utility classes cannot be easily added in markup, keeping the rest of the UI utility-only.

flowchart LR
    A[Plugins] --> B[Directives]
    B --> C[@apply]
    B --> D[@layer]
    B --> E[@config]
    B --> F[Best Practices]
    style B fill:#38bdf8,stroke:#0284c7,color:#fff
    style C fill:#22c55e,stroke:#16a34a,color:#fff

Using @apply to Compose Utilities

/* custom.css */
.btn-primary {
  @apply bg-blue-600 text-white font-medium py-2 px-4 rounded-lg
         hover:bg-blue-700 focus:ring-2 focus:ring-blue-500 focus:ring-offset-2
         transition-colors duration-200;
}

.card {
  @apply bg-white rounded-xl shadow-sm border border-gray-200 p-6;
}

.card-title {
  @apply text-xl font-bold text-gray-900 mb-2;
}

<button class="btn-primary">Click Me</button>
<div class="card">
  <h2 class="card-title">Card with @apply styles</h2>
  <p class="text-gray-600">Uses component classes composed from utilities.</p>
</div>

Expected output: Custom .btn-primary and .card classes that look identical to inline utility classes, composed via @apply.

@apply with Variants

/* custom.css */
.btn-outline {
  @apply border-2 border-blue-600 text-blue-600 font-medium py-2 px-4 rounded-lg
         hover:bg-blue-50 focus:ring-2 focus:ring-blue-500
         active:bg-blue-100
         dark:border-blue-400 dark:text-blue-400 dark:hover:bg-blue-900/20
         transition-all duration-200;
}

<button class="btn-outline">Outline Button</button>

Expected output: An outlined button with hover, focus, active, and dark mode variants all defined via @apply in one CSS rule.

Using @layer for Cascade Control

/* custom.css */
@layer base {
  h1 {
    @apply text-3xl font-bold text-gray-900;
  }
  h2 {
    @apply text-2xl font-semibold text-gray-800;
  }
  a {
    @apply text-blue-600 hover:text-blue-800 underline;
  }
}

@layer components {
  .badge {
    @apply inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium;
  }
  .badge-success {
    @apply badge bg-green-100 text-green-800;
  }
  .badge-error {
    @apply badge bg-red-100 text-red-800;
  }
}

@layer utilities {
  .text-balance {
    text-wrap: balance;
  }
  .scrollbar-thin {
    scrollbar-width: thin;
  }
}

Expected output: Styles organized into base (HTML elements), components (reusable classes), and utilities (single-purpose classes), with Tailwind's cascade order respected.

@config for Multiple Configs

/* admin-styles.css */
@config "./tailwind.admin.config.js";

@import "tailwindcss";

.card-admin {
  @apply bg-gray-900 text-white p-6 rounded-lg;
}

Expected output: The @config directive tells Tailwind to use a different config file for this CSS file, allowing different themes or settings for different parts of an application.

@theme for Design Token Access

/* custom.css */
@import "tailwindcss";

@theme {
  --color-brand: #7c3aed;
  --font-family-display: 'Inter', sans-serif;
  --spacing-page: 2rem;
}

.hero {
  background: var(--color-brand);
  font-family: var(--font-family-display);
  padding: var(--spacing-page);
}

Expected output: CSS custom properties defined via @theme are available throughout the stylesheet, ensuring consistency with Tailwind's design system.

Common Mistakes

1. Using @apply for Everything

@apply defeats Tailwind's purpose when overused. Keep 90 percent of styles as inline utilities. Reserve @apply for third-party overrides and specific cases.

2. @apply Does Not Work with @screen

You cannot combine @apply with @screen or other CSS at-rules. Use responsive utilities inline instead.

3. Confusing @layer Order

Layer order is: base (lowest priority), components, utilities (highest). Styles in lower layers can be overridden by higher layers easily.

4. Forgetting @import "tailwindcss"

The @import "tailwindcss" statement must be in your CSS file for Tailwind to Process directives. Without it, directives are ignored.

5. Nesting @apply Inside @media

Tailwind directives cannot be nested inside CSS at-rules. Move responsive variants inline or use responsive prefixes in @apply.

Practice Questions

1. What does @apply do? It inlines Tailwind utility classes into a custom CSS rule, composing utilities into component classes.

2. What are the three layers in order? base (lowest), components, utilities (highest priority).

3. When should you use @apply? For third-party library overrides, rich text content where utilities cannot be added inline, and legacy code Migration.

4. What does @config do? Specifies a different tailwind config file for the current CSS file.

5. Can @apply use responsive prefixes? Yes: @apply md:text-lg lg:text-xl works inside @apply rules.

Challenge

Create a custom CSS file with: base layer styles for h1-h6 and links, a component layer with .btn and .card composed via @apply, and a utility layer with custom text-wrap and scrollbar utilities.

FAQ

Mini Project

Create a custom component library using @apply: .btn variants (primary, secondary, outline, ghost), .card with header/body/footer, .badge variants (success, error, warning, info), and .form-input with labels.

What's Next

Now master Variants for advanced state customization. Learn how variants enable responsive, state, and group-based styling combinations.