Tutorials Tailwind CSS @tailwind Directives
Ch 5 / 45
Chapter 5 Beginner 9 min read Tailwind CSS

@tailwind Directives

Tailwind uses CSS directives — special at-rules that act as instructions to the PostCSS processor. The three you'll use in every project are @tailwind base, @tailwind components, and @tailwind utilities. Beyond these, Tailwind provides @layer to organise your own CSS, @apply to use utility classes inside CSS files, and @config to load a config file explicitly.

Advertisement
Google Ad Placeholder · 728×90 Leaderboard
What you'll learn
What CSS directives are and why Tailwind uses them
@tailwind base — what Preflight is and when to disable it
@tailwind components — the component layer and what goes here
@tailwind utilities — the main output and why it must be last
@layer — adding your own CSS to the correct cascade layer
@apply — using utility classes inside CSS, with dos and don'ts
@config — loading a custom config path explicitly
The correct order of directives and how cascade specificity works

All Tailwind Directives at a Glance

A directive is a PostCSS at-rule (starts with @) that Tailwind processes and transforms into CSS output. These are not standard CSS — they only work inside a PostCSS build pipeline (CLI, Vite, Next.js, etc.). They are not available in the CDN version's inline config.

@tailwind base
Injects Tailwind's Preflight reset — a modern CSS normaliser that removes browser inconsistencies.
@tailwind components
Injects any classes registered in the components layer — both from plugins and your own @layer blocks.
@tailwind utilities
Injects all utility classes — p-4, flex, text-xl, etc. Must come last so it can override components and base.
@layer
Places your custom CSS into the correct cascade layer — base, components, or utilities — with proper specificity.
@apply
Lets you use Tailwind utility classes inside a CSS rule — extracts them into real CSS declarations.
@config
Explicitly loads a specific tailwind.config.js file — useful in monorepos with multiple configs.

The Three Core @tailwind Directives

These three lines belong at the top of your CSS input file (e.g. src/input.css). They must appear in this exact order — base first, utilities last. Think of them as three layers stacked on top of each other, each able to override the one below.

1
@tailwind base
Injects Preflight — Tailwind's CSS reset. Removes browser default margins on headings and paragraphs, resets box-sizing to border-box, normalises button/input styles, and resets list styles. Based on normalize.css. You can disable it: corePlugins: { preflight: false }.
2
@tailwind components
Injects classes registered in the components layer. This is the right place for multi-class component abstractions like .btn, .card, .badge. Empty by default — fills when you use @layer components { ... } or install plugins like @tailwindcss/forms.
3
@tailwind utilities
Injects all utility classes — every p-4, flex, text-xl, bg-cyan-500, etc. defined by Tailwind and your theme.extend. Must be last so utilities can always override component or base styles.
@tailwind base
Lowest specificity · Reset
→
@tailwind components
Mid specificity · Components
→
@tailwind utilities
Highest specificity · Utilities
→
Your CSS after
Overrides everything above
src/input.css — correct directive order
/* ── src/input.css ─────────────────────────────────── */

/* 1. BASE — Tailwind Preflight reset */
@tailwind base;

/* 2. COMPONENTS — component-layer abstractions */
@tailwind components;

/* 3. UTILITIES — all utility classes (always last) */
@tailwind utilities;

/* ── Your custom CSS goes AFTER the directives ─────── */
/* This CSS has the highest cascade priority and will  */
/* override anything Tailwind injects above it.         */
.custom-scrollbar {
  scrollbar-width: thin;
  scrollbar-color: rgba(6,182,212,.5) transparent;
}
Order matters Never put these directives after your custom CSS. Utilities must come last to override component styles. Writing your own CSS after @tailwind utilities is the correct pattern for global overrides.

@tailwind base & Preflight

@tailwind base injects Preflight — Tailwind's opinionated CSS reset built on top of modern-normalize. It gives every browser an identical baseline so your designs look consistent everywhere.

What Preflight resets Before (browser default) After Preflight
Heading margins h1–h6 have default top/bottom margins All margins removed — add your own with Tailwind
Heading font size h1 = 2em, h2 = 1.5em, etc. All headings inherit body font-size (add text-* yourself)
Box-sizing content-box on most elements border-box on all elements
Paragraph margins Default top/bottom margin All margins removed
List styles ul/ol have bullet/number styles + padding list-style: none, margin: 0, padding: 0
Button styles OS-native button appearance Transparent background, no border — style it yourself
Image display inline (causes gap below images) block — eliminates the gap
Border style Initial (not set) solid on all elements — just add border width
Disable or extend Preflight
/* ── Disable Preflight entirely (existing project with its own reset) */
// tailwind.config.js
module.exports = {
  corePlugins: {
    preflight: false,   // @tailwind base now outputs nothing
  },
};

/* ── Add your own base styles (extend Preflight) */
@layer base {
  /* Custom typography defaults */
  html  { font-size: 16px; scroll-behavior: smooth; }
  body  { font-family: theme('fontFamily.sans'); }

  /* Restore heading sizes if needed */
  h1    { @apply text-4xl font-bold leading-tight; }
  h2    { @apply text-3xl font-semibold leading-tight; }
  h3    { @apply text-2xl font-semibold; }
  h4    { @apply text-xl font-semibold; }

  /* Link defaults */
  a     { @apply text-cyan-500 hover:text-cyan-600 transition-colors; }

  /* Focus ring for accessibility */
  *:focus-visible {
    @apply outline-none ring-2 ring-cyan-500 ring-offset-2;
  }

  /* Dark mode body background */
  body { @apply bg-white dark:bg-gray-950 text-gray-900 dark:text-white; }
}

@tailwind components — The Component Layer

The components layer is where you define reusable, multi-class abstractions. When you find yourself repeating the same long string of utility classes everywhere — like a button, badge, or card — extract them into a named component class using @layer components.

Component classes live between base and utilities in the cascade. This means any utility class applied in HTML will still override a component's styles — the component is a default, not a fixed style.

@layer components — practical examples
/* src/input.css */
@tailwind base;
@tailwind components;   /* ← your @layer blocks inject here */
@tailwind utilities;

@layer components {

  /* ── Button variants ─────────────────────────────────── */
  .btn {
    @apply inline-flex items-center justify-center gap-2 font-semibold
           px-5 py-2.5 rounded-xl transition-all duration-200
           focus:outline-none focus:ring-2 focus:ring-offset-2
           disabled:opacity-50 disabled:cursor-not-allowed cursor-pointer;
  }
  .btn-primary {
    @apply bg-cyan-500 text-white hover:bg-cyan-600 focus:ring-cyan-400;
  }
  .btn-outline {
    @apply border border-gray-300 dark:border-gray-600 text-gray-700
           dark:text-gray-300 hover:border-cyan-400 hover:text-cyan-500;
  }
  .btn-ghost {
    @apply text-gray-600 dark:text-gray-400 hover:bg-gray-100
           dark:hover:bg-gray-800;
  }
  .btn-sm  { @apply px-3.5 py-1.5 text-sm rounded-lg; }
  .btn-lg  { @apply px-8 py-4 text-lg rounded-2xl; }

  /* ── Badge / pill ────────────────────────────────────── */
  .badge {
    @apply inline-flex items-center gap-1.5 px-2.5 py-0.5 rounded-full
           text-xs font-semibold;
  }
  .badge-cyan   { @apply bg-cyan-100 text-cyan-700 dark:bg-cyan-900/30 dark:text-cyan-400; }
  .badge-green  { @apply bg-green-100 text-green-700 dark:bg-green-900/30 dark:text-green-400; }
  .badge-red    { @apply bg-red-100 text-red-700 dark:bg-red-900/30 dark:text-red-400; }

  /* ── Card ────────────────────────────────────────────── */
  .card {
    @apply bg-white dark:bg-gray-900 rounded-2xl border border-gray-100
           dark:border-gray-800 shadow-sm p-6 transition-shadow duration-300;
  }
  .card:hover { @apply shadow-md; }

  /* ── Form input ──────────────────────────────────────── */
  .input {
    @apply w-full rounded-xl border border-gray-300 dark:border-gray-600
           bg-white dark:bg-gray-900 px-4 py-2.5 text-sm text-gray-900
           dark:text-white placeholder:text-gray-400
           focus:outline-none focus:ring-2 focus:ring-cyan-500 focus:border-transparent
           transition-colors duration-200;
  }

}

/* ── Usage in HTML ───────────────────────────────────── */
<button class="btn btn-primary">Save changes</button>
<button class="btn btn-outline btn-sm">Cancel</button>

<!-- Override component with a utility — utilities win -->
<button class="btn btn-primary px-8">Wide button (px-8 overrides .btn's px-5)</button>

<span class="badge badge-cyan">New</span>
<div  class="card">Card content</div>
<input class="input" placeholder="Email address">
Good — use @layer components
Reusable, multi-class patterns you use 5+ times. Buttons, badges, cards, form inputs, navigation links.
Good — shared across components
Classes shared across a design system or UI library that need a single source of truth for styling.
Avoid — one-off styles
Don't extract classes used only once. Use utility classes directly in HTML instead — that's the Tailwind way.
Avoid — layout primitives
Don't extract layout utilities like flex items-center — these are meant to be applied directly.

@layer utilities — Custom Utility Classes

Just as you can add to the components layer, you can add your own utility classes to the utilities layer using @layer utilities. Custom utilities placed here automatically support all Tailwind variants — hover:, dark:, md:, focus: etc.

@layer utilities — custom utility classes
@layer utilities {

  /* Custom scrollbar styling */
  .scrollbar-thin {
    scrollbar-width: thin;
    scrollbar-color: rgba(6,182,212,.5) transparent;
  }
  .scrollbar-hide {
    -ms-overflow-style: none;
    scrollbar-width: none;
  }
  .scrollbar-hide::-webkit-scrollbar { display: none; }

  /* Text balance / pretty (modern CSS) */
  .text-balance { text-wrap: balance; }
  .text-pretty  { text-wrap: pretty; }

  /* Gradient text utility */
  .text-gradient-cyan {
    background: linear-gradient(135deg, #06b6d4, #0ea5e9);
    -webkit-background-clip: text;
    -webkit-text-fill-color: transparent;
    background-clip: text;
  }

  /* GPU acceleration for animations */
  .gpu {
    transform: translateZ(0);
    backface-visibility: hidden;
    will-change: transform;
  }

  /* Safe area insets (mobile notch support) */
  .pb-safe { padding-bottom: env(safe-area-inset-bottom); }
  .pt-safe { padding-top:    env(safe-area-inset-top); }

}

/* ── Usage — supports all variants automatically ──────── */
<div class="scrollbar-hide overflow-y-auto">...</div>
<h1  class="text-gradient-cyan text-5xl font-black">Hello World</h1>
<p   class="text-balance leading-relaxed">Balanced text</p>

<!-- Variants work on custom utilities too -->
<div class="dark:scrollbar-thin hover:text-gradient-cyan md:text-balance"></div>

@apply — Using Utilities Inside CSS

@apply lets you write Tailwind utility class names inside a CSS rule. PostCSS expands them into their equivalent CSS declarations at build time. It is the bridge between the utility-first world and traditional CSS files.

@apply — how it works
/* ── What you write ─────────────────────────────────── */
.my-btn {
  @apply bg-cyan-500 text-white px-6 py-3 rounded-xl font-semibold
         hover:bg-cyan-600 transition-colors duration-200;
}

/* ── What PostCSS outputs ────────────────────────────── */
.my-btn {
  background-color: rgb(6 182 212);
  color: rgb(255 255 255);
  padding-left: 1.5rem;
  padding-right: 1.5rem;
  padding-top: 0.75rem;
  padding-bottom: 0.75rem;
  border-radius: 0.75rem;
  font-weight: 600;
  transition-property: color, background-color, border-color…;
  transition-duration: 200ms;
}
.my-btn:hover {
  background-color: rgb(8 145 178);
}

/* ── @apply also accepts Tailwind's theme() function ─── */
.custom-heading {
  font-size: theme('fontSize.3xl');
  color: theme('colors.cyan.500');
  font-family: theme('fontFamily.display');
}
✓ Good uses of @apply
When @apply makes sense
• Reusable component classes inside @layer components
• Scoped component styles in Vue <style> blocks
• Third-party library overrides where you can't edit HTML
• Base styles for markdown/prose content (h1, a, code)
• Framework-generated HTML you can't add classes to

Rule: if you're writing it inside @layer components, @apply is usually the right choice.
✗ Avoid @apply here
When to avoid @apply
• Creating component abstractions for every element — defeats Tailwind's purpose
• Used because class lists "look too long" in HTML — length is fine in Tailwind
• Replacing utility classes in HTML for styling choices — use HTML directly
• One-off styles used only once — just add them in HTML

Warning: over-using @apply turns Tailwind into a BEM-like CSS framework and loses its maintainability advantages.

@config — Explicit Config Loading

By default Tailwind looks for tailwind.config.js in the project root. The @config directive lets you explicitly specify a different config file path — essential in monorepos or projects with multiple Tailwind configs (e.g. one for the admin panel, one for the customer-facing site).

@config — loading specific config files
/* src/admin.css — uses the admin-specific config */
@config "../tailwind.admin.config.js";

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

/* ─────────────────────────────────────────────────────── */

/* src/site.css — uses the main site config */
@config "../tailwind.site.config.js";

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

/* ── Monorepo example ───────────────────────────────── */
/* packages/ui/src/styles.css */
@config "../../packages/ui/tailwind.config.js";

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

/* ── @config must be the FIRST line in the CSS file ─── */
/* It must appear before any @tailwind directives.        */
/* Only one @config directive per CSS file is allowed.    */
Tip For most single-app projects you never need @config — Tailwind finds your config automatically. Only add it when you have multiple CSS entry points that each need a different configuration.

Complete input.css — Production Template

Here is a complete, well-organised input.css combining all directives. Use this as a starting point for any Tailwind project.

src/input.css — complete production template
/* ══ 1. CORE DIRECTIVES ════════════════════════════════ */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* ══ 2. CUSTOM BASE STYLES ═════════════════════════════ */
@layer base {
  /* Font imports and smooth scrolling */
  html  { @apply scroll-smooth; font-size: 16px; }
  body  { @apply bg-white dark:bg-gray-950 text-gray-900 dark:text-white antialiased; }

  /* Universal focus ring for accessibility */
  *:focus-visible {
    @apply outline-none ring-2 ring-cyan-500 ring-offset-2;
  }

  /* Heading defaults (Preflight removes these) */
  h1 { @apply text-4xl font-bold leading-tight tracking-tight; }
  h2 { @apply text-3xl font-semibold leading-tight; }
  h3 { @apply text-2xl font-semibold; }
  h4 { @apply text-xl font-semibold; }
  h5 { @apply text-lg font-medium; }
  h6 { @apply text-base font-medium; }
}

/* ══ 3. REUSABLE COMPONENT CLASSES ══════════════════════ */
@layer components {

  .btn {
    @apply inline-flex items-center gap-2 font-semibold px-5 py-2.5
           rounded-xl transition-all duration-200 cursor-pointer
           focus:outline-none focus:ring-2 focus:ring-offset-2
           disabled:opacity-50 disabled:cursor-not-allowed;
  }
  .btn-primary { @apply bg-cyan-500 text-white hover:bg-cyan-600 focus:ring-cyan-400; }
  .btn-outline  { @apply border border-current text-gray-700 dark:text-gray-300 hover:border-cyan-400; }

  .card {
    @apply bg-white dark:bg-gray-900 rounded-2xl border border-gray-100
           dark:border-gray-800 shadow-sm p-6;
  }

  .input {
    @apply w-full rounded-xl border border-gray-300 dark:border-gray-600
           bg-white dark:bg-gray-900 px-4 py-2.5 text-sm
           focus:outline-none focus:ring-2 focus:ring-cyan-500 focus:border-transparent;
  }

  .badge {
    @apply inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-semibold;
  }

}

/* ══ 4. CUSTOM UTILITY CLASSES ══════════════════════════ */
@layer utilities {
  .scrollbar-hide  { scrollbar-width: none; }
  .text-balance    { text-wrap: balance; }
  .text-pretty     { text-wrap: pretty; }
  .text-gradient-cyan {
    background: linear-gradient(135deg, #06b6d4, #0ea5e9);
    -webkit-background-clip: text;
    -webkit-text-fill-color: transparent;
    background-clip: text;
  }
}

/* ══ 5. GLOBAL OVERRIDES (highest cascade priority) ══════ */
.tippy-box { @apply rounded-lg text-sm; }  /* third-party override */
Featured Course
Master Tailwind CSS — From Zero to Production (React Course)
Go beyond directives and build complete production UIs. Our structured Tailwind course covers the full utility class system, component patterns, custom config, responsive design, dark mode, and five real-world projects — all with live mentoring.
45 Chapters 10+ Hours 5 Real Projects Certificate Live Mentoring
📄
⭐ 4.9 · 1,200+ students
Tailwind Directives Cheat Sheet
Download our free cheat sheet — all Tailwind CSS directives explained with examples: @tailwind base/components/utilities, @layer base/components/utilities, @apply dos & don'ts, @config, and a complete input.css template.
@tailwind @layer @apply @config Preflight Components
Download Free Cheat Sheet
Chapter Summary
  • Directives are PostCSS at-rules — they only work in a build pipeline (CLI, Vite, Next.js), not in the CDN version which uses inline JavaScript.
  • Three core directives in order: @tailwind base (Preflight reset) → @tailwind components (component layer) → @tailwind utilities (all utilities, must be last).
  • Preflight removes browser defaults for headings, margins, lists, buttons, and images. Disable with corePlugins: { preflight: false } when integrating Tailwind into a project with its own reset.
  • @layer base — add global reset overrides, heading defaults, link styles, and body background colours. These are injected where @tailwind base sits in the file.
  • @layer components — extract reusable multi-class patterns (.btn, .card, .badge) used 5+ times. Utilities in HTML always override component styles — components are defaults, not overrides.
  • @layer utilities — add custom single-purpose utilities (.scrollbar-hide, .text-gradient-cyan). These automatically support all Tailwind variants: dark:, hover:, md:.
  • @apply — use utility classes inside CSS rules. Best inside @layer components and for third-party overrides. Avoid using it as a way to escape writing classes in HTML.
  • @config — must be the first line of a CSS file. Used in monorepos or multi-app setups to load a specific config file. Not needed in typical single-app projects.

Quick Check — Questions & Answers

Click each question to reveal the detailed answer.

CSS specificity follows the cascade — later rules override earlier ones when specificity is equal. By placing @tailwind utilities last, utility classes always win over component and base styles.

For example, if .card in the components layer sets padding: 1.5rem, adding p-8 in HTML should override it. This only works if utilities come after components in the stylesheet.

If you reversed the order — utilities before components — any component style would override your utility classes in HTML, which would break the fundamental Tailwind promise that utility classes are the highest-priority styling mechanism.
Preflight is Tailwind's CSS reset — injected by @tailwind base. It removes browser-default margins from headings and paragraphs, resets list styles, standardises box-sizing to border-box, and gives form elements a neutral baseline.

When to disable it:
• You're adding Tailwind to an existing project that already has its own CSS reset (like Bootstrap or a corporate stylesheet) — Preflight would conflict with it
• You need to preserve certain browser defaults that Preflight removes (e.g. ordered lists with numbers for a content site)
• A third-party UI library assumes browser defaults are present

Disable in config: corePlugins: { preflight: false }
The difference is about intent, cascade position, and variant support:

@layer components — for multi-class, semantic component abstractions (.btn, .card). These inject between base and utilities, so utility classes in HTML can always override them. Best used with @apply.

@layer utilities — for single-purpose, functional utilities (.scrollbar-hide, .text-gradient-cyan). These inject at the same cascade position as Tailwind's built-in utilities. Critically, they automatically gain all Tailwind variant support — you can use dark:scrollbar-hide, md:text-gradient-cyan, hover:text-balance without any extra configuration.

@layer components classes do not automatically get full variant support the same way single-property utilities do.
Use @apply when:
• Writing reusable component classes inside @layer components — .btn, .card, etc.
• Styling Vue component <style scoped> blocks or CSS Modules
• Overriding third-party library elements you can't add classes to directly
• Adding default styles to markdown-rendered HTML (headings, links, code blocks)

Avoid @apply when:
• You're tempted to extract classes because the HTML "looks messy" — long class lists are normal in Tailwind
• Extracting one-off styles used only in one place
• Creating a component class for every element in your project — this defeats the purpose of utility-first and creates a maintenance burden

The Tailwind team recommends using @apply sparingly. If you're using it everywhere, you've reverted to a traditional CSS workflow.
No. Tailwind directives are PostCSS at-rules — they are processed at build time by PostCSS (which the CLI, Vite, and Next.js all run automatically). The CDN version is a JavaScript file that runs in the browser and does not use PostCSS.

With the CDN you cannot use:
• @tailwind base/components/utilities (those three lines go in a separate CSS file)
• @layer with Tailwind-aware behaviour
• @apply
• @config

The CDN does let you write an inline config via <script>tailwind.config = { ... }</script>, but that is a JavaScript object passed to the browser runtime — not a PostCSS directive.

MCQ Quiz — Test Yourself

Select the best answer. The correct option is revealed after you click.

Question 1 of 4
Which of the following is the correct order of the three core Tailwind directives?
Question 2 of 4
You want to create a reusable .btn class that utilities in HTML can still override. Which layer should it go in?
Question 3 of 4
What does @apply bg-cyan-500 text-white px-6 do inside a CSS rule?
Question 4 of 4
You want a custom .scrollbar-hide class that automatically supports dark:, hover:, and md: variants. Which layer do you put it in?

Rate Us on Google

4.8 / 5
Enjoying this tutorial?
Your 5-star review helps other learners discover our free tutorials and encourages us to keep creating quality content.
80+ reviews
Write a Google Review
Join WhatsApp Channel