Tailwind Config File
The
tailwind.config.js
file is the control centre of your Tailwind
project. It is where you tell Tailwind which files to scan, extend
the built-in design system with your own colours, fonts, spacing,
and breakpoints, choose your dark mode strategy, and register
plugins. Understanding this file unlocks everything that makes
Tailwind truly yours.
Config File — Full Structure Overview
Run npx tailwindcss init and
Tailwind generates a minimal
tailwind.config.js. The full
file has eight top-level keys, each controlling a
different aspect of the framework.
'media' (OS preference)
or 'class' (JS toggle).
tw- makes
tw-flex. Avoids conflicts
in legacy projects.
/** @type {import('tailwindcss').Config} */
module.exports = {
content: [], // ← add your file globs here
theme: {
extend: {}, // ← add custom values here
},
plugins: [], // ← add Tailwind plugins here
};
The content Array — File Scanning
The content array tells
Tailwind which files to scan for class names.
Tailwind reads these files as plain text at build time, collects
every class name string it finds, and includes only those in the
output CSS. If a path is wrong, Tailwind outputs an empty
stylesheet.
output.css is under 5 KB or completely unstyled, your
content paths are wrong. Open the file and check — it should be
15–100 KB for a typical project.
/** @type {import('tailwindcss').Config} */
module.exports = {
content: [
// ── Plain HTML / JS project ────────────────────────────
"./src/**/*.{html,js}",
"./*.html",
// ── React / TypeScript project ─────────────────────────
"./index.html",
"./src/**/*.{js,ts,jsx,tsx}",
// ── Vue project ───────────────────────────────────────
"./index.html",
"./src/**/*.{vue,js,ts}",
// ── Next.js (App Router) ──────────────────────────────
"./src/app/**/*.{js,ts,jsx,tsx,mdx}",
"./src/components/**/*.{js,ts,jsx,tsx}",
"./src/pages/**/*.{js,ts,jsx,tsx,mdx}",
// ── Laravel (Blade templates) ─────────────────────────
"./resources/**/*.blade.php",
"./resources/**/*.{js,vue}",
// ── Nuxt project ──────────────────────────────────────
"./components/**/*.vue",
"./layouts/**/*.vue",
"./pages/**/*.vue",
],
};
| Pattern | Matches |
|---|---|
| ./src/**/*.html | All .html files anywhere inside src/ |
| ./src/**/*.{js,jsx} | Both .js and .jsx files anywhere inside src/ |
| ./*.html | Only .html files in the root folder (not subfolders) |
| ./src/**/*.{ts,tsx,mdx} | TypeScript and MDX files inside src/ |
| !./node_modules/** | Exclude a folder (prefix with ! to negate) |
`text-${color}-500`. Tailwind scans files as static
text — it never sees a dynamic expression. Always write the
complete class name: text-cyan-500.
theme vs theme.extend — The Critical Difference
This is the most important distinction in the config file. Getting
it wrong wipes out Tailwind's entire built-in design system for
that key. Always prefer
theme.extend.
theme: { colors: { brand: '#06b6d4' } }
wipes out all 22 default colour palettes. You
lose bg-white, text-gray-500,
bg-blue-500 — everything except
brand.
theme: { extend: { colors: { brand: '#06b6d4' } } }
adds brand alongside all 22 default palettes.
You get bg-brand, text-brand
plus every existing Tailwind colour.
module.exports = {
content: ["./src/**/*.{html,js,jsx,tsx}"],
theme: {
extend: {
/* ✓ Custom colours — added to ALL existing Tailwind colours */
colors: {
brand: {
50: '#ecfeff',
100: '#cffafe',
200: '#a5f3fc',
300: '#67e8f9',
400: '#22d3ee',
500: '#06b6d4', // primary — bg-brand-500
600: '#0891b2',
700: '#0e7490',
800: '#155e75',
900: '#164e63',
950: '#083344',
},
surface: '#09090b', // single value — bg-surface
},
/* ✓ Custom font families */
fontFamily: {
sans: ['Inter', 'system-ui', 'sans-serif'],
display: ['Clash Display', 'sans-serif'],
mono: ['JetBrains Mono', 'monospace'],
},
/* ✓ Custom spacing tokens */
spacing: {
'4.5': '1.125rem', // p-4.5
'18': '4.5rem', // p-18
sidebar: '280px', // w-sidebar
navbar: '64px', // h-navbar
},
/* ✓ Custom border radius */
borderRadius: {
'4xl': '2rem',
'5xl': '3rem',
},
/* ✓ Custom box shadows */
boxShadow: {
glow: '0 0 20px rgba(6,182,212,.4)',
card: '0 4px 32px rgba(0,0,0,.12)',
inset: 'inset 0 2px 8px rgba(0,0,0,.2)',
},
},
},
plugins: [],
};
Custom Colours
Tailwind's colour system uses named palettes with 11 shades
(50–950). You can add your own brand colours in the same format —
once defined, they work with every colour-consuming
utility: bg-brand-500,
text-brand-700,
border-brand-300,
ring-brand-500, and more.
theme: {
extend: {
colors: {
/* Full 11-shade palette — works with ALL colour utilities */
brand: {
50: '#ecfeff', 100: '#cffafe', 200: '#a5f3fc',
300: '#67e8f9', 400: '#22d3ee', 500: '#06b6d4',
600: '#0891b2', 700: '#0e7490', 800: '#155e75',
900: '#164e63', 950: '#083344',
},
/* Single value — generates bg-primary / text-primary etc. */
primary: '#06b6d4',
surface: '#09090b',
/* CSS variables — adapts to dark/light automatically */
accent: 'rgb(var(--accent) / <alpha-value>)',
bg: 'var(--bg)',
/* Extend existing palettes with extra shades */
gray: {
925: '#0f1117', // adds bg-gray-925
975: '#080a0e', // adds bg-gray-975
},
},
},
},
/* Usage in HTML */
<div class="bg-brand-500 text-white">Primary</div>
<div class="bg-brand-50 text-brand-900">Light variant</div>
<div class="border border-brand-300 bg-brand-500/10">Subtle card</div>
Custom Fonts, Spacing & Sizing Tokens
Beyond colours,
theme.extend lets you add
custom font families, spacing values, screen breakpoints, border
radii, and shadows — all usable directly as Tailwind classes
throughout your project.
theme: {
extend: {
/* ── FONT FAMILIES ──────────────────────────────────── */
fontFamily: {
sans: ['Inter var', 'Inter', 'system-ui', 'sans-serif'],
display: ['Clash Display', 'sans-serif'],
mono: ['JetBrains Mono', 'Fira Code', 'monospace'],
},
// usage: font-sans font-display font-mono
/* ── FONT SIZES ─────────────────────────────────────── */
fontSize: {
'10': ['0.625rem', { lineHeight: '1rem' }], // text-10
'2xs': ['0.675rem', { lineHeight: '1rem' }], // text-2xs
},
/* ── SPACING ────────────────────────────────────────── */
spacing: {
'4.5': '1.125rem', // p-4.5 = 18px
'13': '3.25rem', // p-13 = 52px
'18': '4.5rem', // p-18 = 72px
'sidebar': '280px', // w-sidebar
'navbar': '64px', // h-navbar
},
// usage: p-4.5 w-sidebar h-navbar mt-18
/* ── BORDER RADIUS ──────────────────────────────────── */
borderRadius: {
'4xl': '2rem', // rounded-4xl
'5xl': '3rem', // rounded-5xl
},
/* ── BOX SHADOWS ────────────────────────────────────── */
boxShadow: {
'glow': '0 0 20px rgba(6,182,212,.4)', // shadow-glow
'card': '0 4px 32px rgba(0,0,0,.12)', // shadow-card
'float': '0 20px 60px rgba(0,0,0,.25)', // shadow-float
},
/* ── Z-INDEX ────────────────────────────────────────── */
zIndex: {
'60': '60', '70': '70', '80': '80', '90': '90',
},
},
},
Custom Screens — Breakpoints
Tailwind ships five default breakpoints. You can add your own — any custom screen name becomes a responsive prefix instantly usable on any class.
theme: {
extend: {
screens: {
/* Extra small — below Tailwind's default sm: */
'xs': '480px', // xs:flex xs:grid-cols-2
/* Extra large — above 2xl */
'3xl': '1920px', // 3xl:text-7xl 3xl:max-w-screen-3xl
/* Max-width breakpoints (apply only BELOW that width) */
'max-sm': { max: '639px' }, // max-sm:hidden ← mobile only
'max-md': { max: '767px' }, // max-md:flex-col
/* Range breakpoints (apply only between two sizes) */
'tablet': { min: '640px', max: '1023px' },
// tablet:text-lg ← only on tablets
/* Print styles */
'print': { raw: 'print' }, // print:hidden print:text-black
},
},
},
/* Usage examples */
<div class="grid xs:grid-cols-2 sm:grid-cols-3 3xl:grid-cols-6"></div>
<nav class="max-sm:hidden">Desktop nav only</nav>
<p class="print:text-black print:text-base">Print-friendly text</p>
Dark Mode Configuration
Tailwind supports two strategies for dark mode. Choose one and
configure it in the config file — every
dark: prefix in your HTML will
follow this strategy.
prefers-color-scheme media query.
Dark mode activates automatically when the user's OS is in
dark mode. Zero JavaScript needed. Cannot be
toggled by the user on your page.
dark class exists on
<html>. You control it with JavaScript —
great for toggle buttons. Persists via
localStorage.
/* tailwind.config.js — choose your strategy */
module.exports = {
darkMode: 'class', // or 'media'
content: ["./src/**/*.{html,js,jsx,tsx}"],
theme: { extend: {} },
plugins: [],
};
/* ── Usage in HTML ─────────────────────────────────── */
<div class="bg-white text-gray-900 dark:bg-gray-950 dark:text-white">
Adapts to dark mode
</div>
/* ── JavaScript toggle (class strategy only) ────────── */
function toggleDark() {
const html = document.documentElement;
const isDark = html.classList.toggle('dark');
localStorage.setItem('theme', isDark ? 'dark' : 'light');
}
/* ── Prevent flash on page load ─────────────────────── */
<script>
const saved = localStorage.getItem('theme');
const prefer = window.matchMedia('(prefers-color-scheme: dark)').matches;
if (saved === 'dark' || (!saved && prefer)) {
document.documentElement.classList.add('dark');
}
</script>
/* ── Toggle button ──────────────────────────────────── */
<button onclick="toggleDark()"
class="p-2 rounded-lg border border-gray-200 dark:border-gray-700
text-gray-600 dark:text-gray-300 hover:bg-gray-100
dark:hover:bg-gray-800 transition-colors">
Toggle Dark Mode
</button>
Custom Keyframes & Animations
Add your own CSS keyframe animations to Tailwind's config and use
them as
animate-* classes anywhere in
your HTML — just like Tailwind's built-in
animate-spin and
animate-pulse.
theme: {
extend: {
keyframes: {
/* Fade up from below */
fadeUp: {
'0%': { opacity: '0', transform: 'translateY(20px)' },
'100%': { opacity: '1', transform: 'translateY(0)' },
},
/* Fade in */
fadeIn: {
'0%': { opacity: '0' },
'100%': { opacity: '1' },
},
/* Slide in from left */
slideIn: {
'0%': { transform: 'translateX(-100%)', opacity: '0' },
'100%': { transform: 'translateX(0)', opacity: '1' },
},
/* Shimmer loading effect */
shimmer: {
'0%': { backgroundPosition: '-200% 0' },
'100%': { backgroundPosition: '200% 0' },
},
/* Scale pop */
pop: {
'0%': { transform: 'scale(0.8)', opacity: '0' },
'60%': { transform: 'scale(1.05)' },
'100%': { transform: 'scale(1)', opacity: '1' },
},
},
animation: {
'fade-up': 'fadeUp 0.5s ease-out', // animate-fade-up
'fade-in': 'fadeIn 0.4s ease-out', // animate-fade-in
'slide-in': 'slideIn 0.3s ease-out', // animate-slide-in
'shimmer': 'shimmer 2s linear infinite', // animate-shimmer
'pop': 'pop 0.35s cubic-bezier(.26,1.4,.56,1)', // animate-pop
},
},
},
/* Usage */
<div class="animate-fade-up">Fades up on render</div>
<div class="animate-pop">Pops in with scale</div>
<div class="animate-shimmer bg-gradient-to-r from-gray-200 via-gray-100 to-gray-200">
Skeleton loader
</div>
Plugins
Tailwind's official plugins add new utility classes for common patterns that aren't built into the core. Install them via npm and register in the config — they integrate seamlessly with the entire Tailwind ecosystem including dark mode and responsive prefixes.
prose class for
beautiful typographic defaults on HTML content.
aspect-w-* and
aspect-h-* classes for
responsive aspect ratios.
line-clamp-{n} classes
(built-in in v3.3+, plugin for older versions).
btn,
card,
modal.
# Install plugins
npm install -D @tailwindcss/forms @tailwindcss/typography @tailwindcss/aspect-ratio
/* tailwind.config.js */
module.exports = {
content: ["./src/**/*.{html,js,jsx,tsx}"],
theme: { extend: {} },
plugins: [
require('@tailwindcss/forms'),
require('@tailwindcss/typography'),
require('@tailwindcss/aspect-ratio'),
],
};
/* Usage */
<article class="prose prose-lg dark:prose-invert max-w-3xl">
<h1>Beautiful typography</h1>
<p>All your HTML content styled automatically.</p>
</article>
<input type="text" class="form-input rounded-lg border-gray-300 focus:border-cyan-500">
<select class="form-select rounded-lg"></select>
Complete Production Config
Here is a comprehensive, fully commented
tailwind.config.js you can use
as a starting point for any real project.
/** @type {import('tailwindcss').Config} */
module.exports = {
/* ── File scanning ───────────────────────────────────── */
content: [
"./index.html",
"./src/**/*.{js,ts,jsx,tsx,vue,svelte}",
],
/* ── Dark Mode ───────────────────────────────────────── */
darkMode: 'class',
/* ── Design System ───────────────────────────────────── */
theme: {
extend: {
colors: {
brand: {
'50': '#ecfeff', '100': '#cffafe', '200': '#a5f3fc',
'300': '#67e8f9', '400': '#22d3ee', '500': '#06b6d4',
'600': '#0891b2', '700': '#0e7490', '800': '#155e75',
'900': '#164e63', '950': '#083344',
},
},
fontFamily: {
sans: ['Inter', 'system-ui', 'sans-serif'],
display: ['Clash Display', 'sans-serif'],
mono: ['JetBrains Mono', 'monospace'],
},
spacing: {
sidebar: '280px',
navbar: '64px',
},
screens: {
'xs': '480px',
'3xl': '1920px',
},
borderRadius: {
'4xl': '2rem',
},
boxShadow: {
glow: '0 0 20px rgba(6,182,212,.4)',
},
keyframes: {
fadeUp: {
'0%': { opacity: '0', transform: 'translateY(20px)' },
'100%': { opacity: '1', transform: 'translateY(0)' },
},
},
animation: {
'fade-up': 'fadeUp 0.5s ease-out',
},
},
},
/* ── Plugins ─────────────────────────────────────────── */
plugins: [
require('@tailwindcss/forms'),
require('@tailwindcss/typography'),
require('@tailwindcss/aspect-ratio'),
],
};
- tailwind.config.js is the control centre — it tells Tailwind which files to scan, extends the design system, configures dark mode, and registers plugins.
- The content array is the most critical setting. Wrong paths = empty CSS. Use glob patterns to match all your HTML, JS, JSX, TSX, Vue, and Svelte files.
-
theme vs theme.extend: use
theme.extendto add values without wiping defaults. Only usethemedirectly when you deliberately want to replace the entire default for a key. -
Custom colours in
theme.extend.colorswork with all colour utilities automatically —bg-brand-500,text-brand-50,border-brand-300, and opacity modifiers. -
Custom fonts, spacing, radii, and shadows all
work the same way — add to
theme.extendand use as Tailwind classes immediately. -
Dark mode: use
'media'for automatic OS-based switching, or'class'for a JavaScript-controlled toggle with localStorage persistence. -
Custom keyframes defined in
theme.extend.keyframesbecomeanimate-*classes when registered intheme.extend.animation. - Official plugins — @tailwindcss/forms, @tailwindcss/typography, and @tailwindcss/aspect-ratio — add powerful utilities not in the Tailwind core.
Quick Check — Questions & Answers
Click each question to reveal the detailed answer.
If the
content paths are wrong, Tailwind finds
no class names and outputs an empty stylesheet — your HTML
will appear completely unstyled even though Tailwind ran
without errors.Quick diagnosis: if
dist/output.css is under 5KB, your content
paths are wrong. A working project typically produces
15–100KB of output CSS.
theme directly
replaces Tailwind's entire default colour palette
with only your custom value. You lose all 22 built-in
palettes: gray, red, blue, green, cyan, purple, etc.Classes like
bg-white,
text-gray-500, bg-blue-500 stop
working because those colours no longer exist in your
config.Fix: always nest inside
theme.extend — this merges your brand colours
alongside Tailwind's defaults so you get both.
theme.extend.screens:theme: { extend: { screens: { 'xs': '480px' } } }Once added,
xs: works as a responsive prefix on
any class — xs:flex,
xs:grid-cols-2, xs:text-lg. It
follows Tailwind's mobile-first model so it applies at 480px
and above.Note: Tailwind's built-in breakpoints start at
sm: = 640px, so adding
xs: = 480px fills the gap between mobile and
small — useful for large phones and small tablets.
'media' — uses the CSS
prefers-color-scheme: dark media query. Dark
mode activates automatically when the user's OS is in dark
mode. No JavaScript needed, but users cannot toggle dark
mode on your page independently of their OS setting.'class' — dark mode activates
when the dark class is present on
<html>. You control this with JavaScript,
giving users a toggle button. Persist the preference with
localStorage so it survives page refreshes.
Most production sites use this strategy.
theme.extend:1. Define the keyframes:
keyframes: { fadeUp: { '0%': { opacity: '0', transform:
'translateY(20px)' }, '100%': { opacity: '1', transform:
'translateY(0)' } } }2. Register the animation:
animation: { 'fade-up': 'fadeUp 0.5s ease-out' }Tailwind then generates the
animate-fade-up class automatically. Use it in
HTML:<div class="animate-fade-up">...</div>You can also combine with responsive and hover variants:
md:animate-fade-up.
MCQ Quiz — Test Yourself
Select the best answer. The correct option is revealed after you click.
dist/output.css
file is only 3KB and nothing is styled. What is
the most likely cause?
primary: '#06b6d4'
while keeping all default Tailwind colours. Where do you put it?
darkMode
value allows users to toggle dark mode with a button on your
website?
prose
class for beautiful typographic content styling?
Rate Us on Google
Join Our Learning Community
Connect with thousands of learners, get daily tips, ask questions and stay updated with new tutorials.