How to use custom color themes in TailwindCSS v4

Question

My tailwind.config.js in v3 looks like this, but I can't find a way to use it in v4:

theme: {
  extend: {
    colors: {
      lightHover: '#fcf4ff',
      darkHover: '#2a004a',
      darktheme: '#11001f',
    },
    fontFamily: {
      Outfit: ["Outfit", "sans-serif"],
      Ovo: ["Ovo", "serif"]
    },
    boxShadow: {
      'black': '4px 4px 0 #000',
      'white': '4px 4px 0 #fff',
    },
    gridTemplateColumns: {
      'auto': 'repeat(auto-fit, minmax(200px, 1fr))'
    }
  },
},
darkMode: 'selector',

This is a piece of code for v3,and I can customize the color of the dark theme instead of using black like this:

<div className="dark:bg-darktheme"></div>

But how can I do the same thing in v4? Does anyone have the same problem? Just write bg-black?

Can't find detailed tailwind.config.js documentation.

Answer 1

Starting from TailwindCSS v4, the CSS-first configuration is preferred, meaning the init process and the tailwind.config.js file have been removed.

• What's breaking changes from TailwindCSS v4
• New CSS-first configuration from TailwindCSS v4
• Removed @tailwind directives
• Deprecated: Sass, Less and Stylus preprocessors support

Customize theme with CSS-first directives

In a CSS-first configuration, several directives are available. For theme customization, you can primarily use the @theme directive:

@import "tailwindcss";

@theme {
  --font-display: "Satoshi", "sans-serif";
  --breakpoint-3xl: 120rem;
  --color-avocado-100: oklch(0.99 0 0);
  --color-avocado-200: oklch(0.98 0.04 113.22);
  --color-avocado-300: oklch(0.94 0.11 115.03);
  --color-avocado-400: oklch(0.92 0.19 114.08);
  --color-avocado-500: oklch(0.84 0.18 117.33);
  --color-avocado-600: oklch(0.53 0.12 118.34);
  --ease-fluid: cubic-bezier(0.3, 0, 0, 1);
  --ease-snappy: cubic-bezier(0.2, 0, 0, 1);
  /* ... */
}

• @theme directive

Theme variables are defined in namespaces and each namespace corresponds to one or more utility class or variant APIs.

• Theme variable namespaces
• Default theme variable reference

Set dark directive with CSS-first

Starting from v4, a new @custom-variant directive is introduced, allowing you to customize the behavior of dark: or create your own custom variants, such as coffee:.

• @custom-variant directive
• @variant directive

document.querySelector('button').addEventListener('click', () => {
  document.documentElement.classList.toggle('dark');
});

<script src="https://unpkg.com/@tailwindcss/browser"></script>
<style type="text/tailwindcss">
/* changed the behavior of dark: (default: based on prefers-color-scheme) to work based on the presence of the .dark parent class */
@custom-variant dark (&:where(.dark, .dark *));

@theme {
  --color-pink: #eb6bd8;
}

@layer theme {
  :root, :host {
    @variant dark {
      --color-pink: #8e0d7a;
    }
  }
}
</style>

<button class="size-20 bg-pink dark:text-white">Click Here</button>
<div class="w-50 h-12 bg-purple-200 dark:bg-purple-900 dark:text-white">
  Lorem Ipsum
</div>

Additionally, without JS, it's possible to detect whether the system prefers light or dark mode by default, and integrate this into the dark: variant behavior. For this, your light/dark toggle needs to support three states: system/light/dark. You'll also need an extra .system class, but the dark: variant can work the same way with both .system and .dark classes:

• Manual dark mode toggle, but by default it should follow the system scheme

How to declare dark or more themes in TailwindCSS v4

Following the dark example, an unlimited number of variants and themes can be declared.

document.querySelector('#toggle-dark').addEventListener('click', () => {
  document.documentElement.classList.toggle('dark');
  document.documentElement.classList.remove('coffee');
});

document.querySelector('#toggle-coffee').addEventListener('click', () => {
  document.documentElement.classList.toggle('coffee');
  document.documentElement.classList.remove('dark');
});

<script src="https://unpkg.com/@tailwindcss/browser"></script>
<style type="text/tailwindcss">
@custom-variant dark (&:where(.dark, .dark *));
@custom-variant coffee (&:where(.coffee, .coffee *));

@theme {
  --color-pink: #eb6bd8;
  --color-tsunami: #77b4ea;
}

@layer theme {
  :root, :host {
    @variant dark {
      --color-pink: #8e0d7a;
      --color-tsunami: #0d84ec;
    }
    @variant coffee {
      --color-pink: #a67ca8;
      --color-tsunami: #b57913;
    }
  }
}
</style>

<div class="mb-4">
  <button id="toggle-dark" class="px-4 py-2 bg-sky-600 hover:bg-sky-950 text-white cursor-pointer rounded-lg">Toggle Dark</button>
  <button id="toggle-coffee" class="px-4 py-2 bg-amber-600 hover:bg-amber-950 text-white  cursor-pointer rounded-lg">Toggle Coffee</button>
</div>

<button class="size-20 bg-pink dark:text-white coffee:text-amber-50">Hello World</button>
<div class="w-50 h-12 bg-tsunami dark:text-white coffee:text-orange-200">
  Lorem Ipsum
</div>

References:

• How to override theme variables in TailwindCSS v4 - @theme vs @layer theme vs :root
• When should I use * and when should I use :root, :host as the parent selector?
• How @variant dark can be combined with @theme in a CSS-first configuration to override dark mode colors
• Should I use @theme or @theme inline?
• How can I safely introduce the use of light-dark() without increasing the minimum browser version requirement?

Disable dark mode, use light: instead of dark::

• TailwindCSS: How to do a light mode only modification?
• How to disable dark mode in TailwindCSS 4