@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.
@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
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.
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.
normalize.css. You can disable it:
corePlugins: { preflight: false }.
.btn, .card, .badge. Empty by default —
fills when you use @layer components { ... } or install plugins like
@tailwindcss/forms.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.
/* ── 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;
}
@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 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.
/* 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">
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 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.
/* ── 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');
}
@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.
• 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).
/* 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. */
@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.
/* ══ 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 */
- 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 basesits 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 componentsand 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.
@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.
@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 }
@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.
• 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.
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•
@configThe 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.
.btn class that utilities in HTML
can still override. Which layer should it go in?@apply bg-cyan-500 text-white px-6
do inside a CSS rule?.scrollbar-hide class that
automatically supports dark:,
hover:, and md: variants. Which layer do you
put it in?
Rate Us on Google
Join Our Learning Community
Connect with thousands of learners, get daily tips, ask questions and stay updated with new tutorials.