Tailwind CSS - Customizing Colors

Tailwind CSS - Customizing Colors

Tailwind CSS provides a comprehensive and expertly-crafted default color palette out of the box. However, for most projects, you’ll want to customize this palette to match your brand’s specific identity. This tutorial will guide you through modern techniques for managing and extending colors in your project.

The default color palette is a great starting point, featuring a wide range of grays and a vibrant set of colors, each with 11 shades. You can browse the full default palette in the official Tailwind documentation.

Best Practice: Extending the Color Palette

Instead of replacing Tailwind’s entire color palette, the recommended approach is to extend it with your custom colors. This way, you retain access to the useful default colors while adding your own. You can add new colors inside the theme.extend.colors object in your tailwind.config.js file.

This method is ideal for adding brand colors, semantic colors, or additional shades to existing colors.

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    extend: {
      colors: {
        'brand-primary': '#4F46E5',
        'brand-secondary': '#D97706',
        'brown': {
          50: '#fdf8f6',
          100: '#f2e8e5',
          200: '#eaddd7',
          300: '#e0cec7',
          400: '#d2bab0',
          500: '#bfa094',
          600: '#a18072',
          700: '#977669',
          800: '#846358',
          900: '#43302b',
          950: '#2c1e1a',
        },
      }
    },
  },\n  plugins: [],
}

With this configuration, you can now use classes like bg-brand-primary or text-brown-700.

Structuring Your Colors

Naming Conventions

While you can name colors anything you like, it’s a best practice to use semantic or abstract names rather than literal ones. This makes your design system more robust and easier to theme.

For example, instead of 'blue', use 'primary'. This allows you to change what ‘primary’ means in the future without having to refactor all your components.

const colors = require('tailwindcss/colors')

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    extend: {
      colors: {
        'primary': colors.indigo['600'],
        'secondary': colors.amber['500'],
        'neutral': colors.slate,
      }
    },
  },
}

Nested Color Objects

When a color has multiple shades, group them in a nested object. The keys will be combined to form class names like bg-tahiti-400.

Use the special DEFAULT key to define a base color that doesn’t require a shade suffix. This creates classes like bg-tahiti.

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    extend: {
      colors: {
        'tahiti': {
          light: '#67e8f9',
          DEFAULT: '#06b6d4', // Corresponds to `bg-tahiti`
          dark: '#0e7490',
        },
      },
    },
  },
}

Using Arbitrary Values

For one-off colors that don’t need to be part of your theme, you can use Tailwind’s arbitrary value syntax. This is perfect for unique gradients or specific hex codes that are used only once.

<!-- This generates a class for the specific hex code on the fly -->
<button class="bg-[#1da1f2] text-white p-2 rounded-lg">
  Share on Twitter
</button>

<!-- Can be used for text, borders, etc. -->
<p class="text-[#bada55]">A unique color!</p>

Advanced: Using CSS Variables for Colors

A powerful technique for theming (e.g., light/dark mode) is to define your colors using CSS Custom Properties and reference them in your Tailwind config. This allows you to change the theme by simply changing the CSS variables, often with a bit of JavaScript.

The key is to define the variables as color channels (three numbers for R, G, B) and then use Tailwind’s special <alpha-value> placeholder to allow opacity modifiers to work correctly.

Step 1: Define CSS variables in your global CSS file.

src/input.css

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

@layer base {
  :root {
    --color-primary: 88 80 236; /* R G B channels for a shade of indigo */
    --color-secondary: 234 179 8; /* R G B channels for a shade of amber */
  }
  .dark {
    --color-primary: 167 139 250;
    --color-secondary: 250 204 21;
  }
}

Step 2: Reference these variables in tailwind.config.js.

/** @type {import('tailwindcss').Config} */
module.exports = {
  darkMode: 'class', // Enable class-based dark mode
  theme: {
    extend: {
      colors: {
        primary: 'rgb(var(--color-primary) / <alpha-value>)',
        secondary: 'rgb(var(--color-secondary) / <alpha-value>)',
      }
    }
  }
}

Now you can use classes like bg-primary, text-secondary, and even apply opacity with bg-primary/50. Toggling the .dark class on the <html> element will dynamically change your site’s theme.

Overriding the Default Palette

If you need complete control and want to disable all default colors, you can define your palette directly under theme.colors. Warning: This is a destructive action and will remove all of Tailwind’s built-in colors. This is generally only needed for highly constrained design systems.

const colors = require('tailwindcss/colors')

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    // This REPLACES the entire color palette
    colors: {
      transparent: 'transparent',
      current: 'currentColor',
      white: '#ffffff',
      black: '#000000',
      primary: colors.indigo, // You can still pull in defaults
      neutral: colors.slate,
    },
  },
}