Tailwind CSS Configuration — Customizing the Default Theme

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

Tailwind CSS configuration is managed through tailwind.config.js where you extend or override the default theme with your project's custom colors, fonts, spacing, breakpoints, and more.

What You'll Learn

You will learn how to customize the Tailwind theme using the config file, the difference between extend and override, and how to add custom values for colors, fonts, spacing, and breakpoints.

Why It Matters

Every project has unique brand colors and typography. DodaTech's Durga Antivirus Pro dashboard uses a custom Tailwind config with brand colors, a custom font family, and custom breakpoints for the sidebar layout.

Real-World Use

Doda Browser's settings panel defines custom colors (brand-purple, brand-indigo) and custom spacing in tailwind.config.js, ensuring all team members use consistent values without memorizing hex codes.

flowchart LR
    A[Installation] --> B[Configuration]
    B --> C[Theme Extend]
    B --> D[Theme Override]
    B --> E[Custom Values]
    B --> F[Plugins]
    style B fill:#38bdf8,stroke:#0284c7,color:#fff
    style C fill:#22c55e,stroke:#16a34a,color:#fff

Basic Configuration

// tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ["./**/*.{html,js}"],
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#f5f3ff',
          100: '#ede9fe',
          500: '#7c3aed',
          600: '#6d28d9',
          700: '#5b21b6',
        },
      },
      fontFamily: {
        display: ['Inter', 'sans-serif'],
      },
    },
  },
  plugins: [],
}

Expected output: Classes like bg-brand-500, text-brand-700, and font-display become available alongside all default Tailwind utilities.

Extend vs Override

// EXTEND — adds new values without removing defaults
module.exports = {
  theme: {
    extend: {
      spacing: {
        '18': '4.5rem',
        '88': '22rem',
      },
    },
  },
}

// OVERRIDE — replaces the entire default scale
module.exports = {
  theme: {
    spacing: {
      '1': '4px',
      '2': '8px',
      '3': '12px',
    },
    // Default spacing values are gone
  },
}

Expected output: Extend adds p-18 and p-88 while keeping p-1 through p-96. Override removes all defaults and only provides the defined values.

Custom Colors with Opacity

module.exports = {
  theme: {
    extend: {
      colors: {
        dodatech: {
          purple: '#7c3aed',
          'purple-light': '#a78bfa',
          blue: '#3b82f6',
          green: '#22c55e',
        },
      },
    },
  },
}

<div class="bg-dodatech-purple text-white p-4 rounded">
  DodaTech Brand
</div>
<div class="bg-dodatech-purple-light text-dodatech-purple p-4 rounded mt-2">
  Light Variant
</div>

Expected output: Custom brand colors applied with utility classes. Note that opacity modifiers like bg-dodatech-purple/50 work automatically.

Custom Breakpoints

module.exports = {
  theme: {
    extend: {
      screens: {
        'xs': '480px',
        '3xl': '1600px',
        'sidebar': '900px',
      },
    },
  },
}

<div class="grid grid-cols-2 xs:grid-cols-3 sidebar:grid-cols-4 3xl:grid-cols-6 gap-4">
  <div class="bg-gray-100 p-4 rounded">Item 1</div>
  <div class="bg-gray-100 p-4 rounded">Item 2</div>
  <div class="bg-gray-100 p-4 rounded">Item 3</div>
  <div class="bg-gray-100 p-4 rounded">Item 4</div>
</div>

Expected output: Grid columns change at custom breakpoints: 2 columns by default, 3 at 480px, 4 at 900px, 6 at 1600px.

Common Mistakes

1. Overriding Instead of Extending

Using theme.colors instead of theme.extend.colors replaces all default colors, breaking bg-blue-500, text-red-600, and hundreds of other utilities.

2. Using Invalid Color Names

Color keys with spaces or special characters must be quoted: 'brand-purple-light' not brand-purple-light.

3. Not Restarting the Build Server

Changes to tailwind.config.js require a build restart. PostCSS or CLI watchers may need restarting to pick up new config values.

4. Duplicate Config Keys

Having the same key in theme.extend and theme causes unexpected behavior. Config merging follows Tailwind's specific precedence rules.

5. Forgetting the @type JSDoc Comment

Without the JSDoc @type {import('tailwindcss').Config}, editors lack autocomplete for config properties.

Practice Questions

1. Where do custom theme values go in the config? Inside theme.extend to add values without removing defaults, or directly in theme to override the default scale entirely.

2. What is the difference between extend and override? Extend merges new values with defaults. Override replaces the entire default scale for that property.

3. How do you add a custom font family? Add a fontFamily key in theme.extend with an array of font names like ['Inter', 'sans-serif'].

4. Can you name breakpoints anything? Yes. Breakpoint keys become responsive prefixes like xs: or sidebar:.

5. What restarts are needed config changes? The build pipeline (PostCSS or CLI) must be restarted after changing tailwind.config.js.

Challenge

Create a custom config that adds 3 brand colors (primary-teal, secondary-coral, accent-gold), a custom font pair (heading and body), and two custom breakpoints (tablet at 700px, desktop-wide at 1440px). Generate classes for each.

FAQ

Mini Project

Create a tailwind.config.js for a brand that needs: 5 custom colors (primary, secondary, accent, neutral, danger), custom spacing (18, 88, 128), custom font (Inter for headings, Source Sans for body), and a print-specific breakpoint.

What's Next

With configuration mastered, explore Utility-First Fundamentals to understand how to compose utilities. Then learn Spacing and Sizing for layout control.