Tutorials Tailwind CSS Tailwind Config File
Ch 4 / 45
Chapter 4 Beginner 11 min read Tailwind CSS

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.

Advertisement
Google Ad Placeholder · 728×90 Leaderboard
What you'll learn
The structure of tailwind.config.js — all top-level keys explained
The content array — glob patterns, why it matters, and common mistakes
theme vs theme.extend — the critical difference and when to use each
Custom colours — adding brand palettes with full shade ranges
Custom fonts, spacing, border radius, and shadow tokens
Custom screens — adding extra breakpoints to the responsive system
Dark mode strategies — 'media' vs 'class' with a practical JS toggle
Custom keyframes, animations, and official Tailwind plugins

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.

content
Glob paths pointing to every file containing Tailwind class names. Wrong paths = empty CSS. Critical.
theme
The entire design system — colours, fonts, spacing, shadows, border radius, screens, and more.
theme.extend
Merge your custom values with Tailwind's defaults without wiping built-in utilities. Always use this.
darkMode
Controls how dark mode works — 'media' (OS preference) or 'class' (JS toggle).
plugins
Array of Tailwind plugins — official ones like @tailwindcss/forms, typography, and aspect-ratio.
prefix
Add a string prefix to all classes — e.g. tw- makes tw-flex. Avoids conflicts in legacy projects.
presets
Share a base config across multiple projects — useful in monorepos or design systems.
corePlugins
Disable specific built-in utility categories you don't use to slightly reduce output size.
tailwind.config.js — minimal generated file
/** @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.

Critical Rule Tailwind cannot output a class it never sees in a file. If your 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.
content — glob patterns for every project type
/** @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)
Tip Never build class names with string concatenation like `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.

✗ REPLACES Using theme directly
Setting theme: { colors: { brand: '#06b6d4' } } wipes out all 22 default colour palettes. You lose bg-white, text-gray-500, bg-blue-500 — everything except brand.
✓ MERGES Using theme.extend
Setting theme: { extend: { colors: { brand: '#06b6d4' } } } adds brand alongside all 22 default palettes. You get bg-brand, text-brand plus every existing Tailwind colour.
theme.extend — the safe pattern
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.

Custom colours — all patterns
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.

Custom fonts, spacing, radii, shadows
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.

(none)
0px+ · default
xs:
480px+ · custom
sm:
640px+
md:
768px+
lg:
1024px+
xl:
1280px+
2xl:
1536px+
3xl:
1920px+ · custom
Custom screens — min-width, max-width, and ranges
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.

'media'
OS / Browser Preference
Uses the CSS 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.
'class'
JavaScript Toggle
Dark mode activates when a dark class exists on <html>. You control it with JavaScript — great for toggle buttons. Persists via localStorage.
Dark mode — config + JS toggle implementation
/* 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.

Custom keyframes and animations
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.

@tailwindcss/forms
Resets browser form element styles to a consistent, styleable baseline.
npm install -D @tailwindcss/forms
@tailwindcss/typography
Adds the prose class for beautiful typographic defaults on HTML content.
npm install -D @tailwindcss/typography
@tailwindcss/aspect-ratio
Adds aspect-w-* and aspect-h-* classes for responsive aspect ratios.
npm install -D @tailwindcss/aspect-ratio
@tailwindcss/line-clamp
Adds line-clamp-{n} classes (built-in in v3.3+, plugin for older versions).
npm install -D @tailwindcss/line-clamp
tailwindcss-animate
Community plugin — adds comprehensive animation utilities used by shadcn/ui.
npm install -D tailwindcss-animate
daisyUI
Component class plugin — adds semantic component classes like btn, card, modal.
npm install -D daisyui
plugins — install and register
# 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.

tailwind.config.js — complete production template
/** @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'),
  ],

};
Featured Course
Master Tailwind CSS — From Zero to Production (React Course)
Go beyond config files and build complete UIs. Our structured course covers the full Tailwind design system, responsive layouts, dark mode, component patterns, and five real-world production projects — all with live mentoring from industry pros.
45 Chapters 10+ Hours 5 Real Projects Certificate Live Mentoring
🗂️
⭐ 4.9 · 1,200+ students
Tailwind Config File Cheat Sheet
Download our free cheat sheet — every tailwind.config.js option including content patterns, theme.extend recipes, custom colours, screens, darkMode, keyframes, and plugin setup. Perfect to keep open while configuring a new project.
content theme.extend Colors Fonts Screens darkMode Plugins
Download Free Cheat Sheet
Chapter Summary
  • 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.extend to add values without wiping defaults. Only use theme directly when you deliberately want to replace the entire default for a key.
  • Custom colours in theme.extend.colors work 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.extend and 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.keyframes become animate-* classes when registered in theme.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.

Tailwind's build process works by scanning your source files as plain text and collecting every Tailwind class name string it finds. It then outputs only those classes in the final CSS — all other utilities are excluded to keep the file tiny.

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.
Placing it in 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.
Add it to 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.
Two steps in 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.

Question 1 of 4
Your dist/output.css file is only 3KB and nothing is styled. What is the most likely cause?
Question 2 of 4
You want to add a custom colour primary: '#06b6d4' while keeping all default Tailwind colours. Where do you put it?
Question 3 of 4
Which darkMode value allows users to toggle dark mode with a button on your website?
Question 4 of 4
Which official Tailwind plugin adds the prose class for beautiful typographic content styling?

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