sodcalculator

10 Tech How-To

How to Add Custom Colors in Tailwind CSS v4

Guide 10-43896 · Updated · Step by step

Tailwind CSS v4 changed how you define custom colors. Instead of editing a tailwind.config.js file, you use CSS variables and the new @theme directive directly in your stylesheet. This guide shows you exactly how to add your own brand colors, create color scales, and use them in your HTML classes.

What You’ll Need

  • A project with Tailwind CSS v4 installed (via npm, the Play CDN, or the Vite plugin).
  • A code editor to modify your main CSS file (usually src/index.css or app.css).
  • Basic familiarity with CSS custom properties (variables).

Step-by-Step

  1. Open your main CSS file. This is the file where you import Tailwind. It typically starts with @import "tailwindcss";.
  2. Add an @theme block after the import. The @theme directive is where you define design tokens like colors, fonts, and spacing. It replaces the theme section of the old config file.
  3. Define a custom color using a CSS variable. Inside @theme, write --color-*: value;. The * is the name you’ll use in your classes. For example, to add a color named brand, write:
    @theme {
      --color-brand: #3490dc;
    }

    Now you can use bg-brand, text-brand, border-brand, etc.

  4. Create a color scale for multiple shades. Tailwind expects shades like 50, 100, …, 900. Define each as a separate variable:
    @theme {
      --color-primary-50: #eff6ff;
      --color-primary-100: #dbeafe;
      --color-primary-500: #3b82f6;
      --color-primary-700: #1d4ed8;
    }

    Then use bg-primary-500 or text-primary-100.

  5. Use the @theme block with a custom name (optional). You can also namespace your colors, e.g., --color-company-blue: #0055ff;. This generates classes like bg-company-blue.
  6. Reference the variable in regular CSS (if needed). If you want to use the color outside of Tailwind classes, you can access it as a normal CSS variable: color: var(--color-brand);.
  7. Rebuild your CSS. If you’re using a build step (Vite, PostCSS), run your build command (npm run build or npm run dev). Tailwind v4 scans your source files and generates the utilities on-demand.
  8. Verify in your HTML. Add a class like bg-brand or text-primary-500 to an element and check that the color applies.

Common Mistakes

  • Using the old config file. In v4, tailwind.config.js is optional and not used for theme customization by default. Don’t waste time editing it.
  • Forgetting the --color- prefix. The variable must start with --color- for Tailwind to recognize it as a color token. If you write --brand: #fff, it won’t generate any utilities.
  • Putting @theme inside a media query or after other CSS rules. @theme should be at the top level of your stylesheet, ideally right after the import.
  • Using hex values without the hash. Always include the # or use rgb()/hsl() syntax.
  • Not rebuilding. If you don’t see the new color, it’s often because the CSS hasn’t been regenerated.

Tips

  • Use color scales consistently. Follow Tailwind’s default naming (50–900) so your custom colors work seamlessly with opacity modifiers like bg-primary-500/50.
  • Define colors in a separate file. If you have many colors, create a theme.css and import it into your main CSS file to keep things organized.
  • Use the @theme block for other tokens too. You can define spacing, fonts, and more. For example, --font-display: "Inter", sans-serif; gives you font-display.
  • Leverage CSS variables for dynamic themes. You can override the variables in a data-theme attribute or media query to support dark mode or theming.
  • Check the official docs. Tailwind v4 docs have a comprehensive theme variable reference.

Troubleshooting

  • My custom color doesn’t appear. First, ensure the variable name is correct and starts with --color-. Then check that your CSS file is the one being imported by your build tool. If you’re using the Play CDN, note that @theme might not work; use the CDN’s tailwind.config option instead.
  • Classes like bg-brand are not generated. Tailwind v4 generates utilities only when it finds the class in your content files. Make sure your HTML or template files are included in the content detection (usually automatic). If you’re using a framework like Laravel, verify the @source directive.
  • The color shows but with a different shade. Check if you have a conflicting CSS variable or if the class name collides with a default Tailwind color. For example, --color-red would override the default red palette.
  • Opacity modifiers don’t work. They only work with colors defined in the --color-* format. If you define a color as a regular CSS variable, opacity modifiers won’t apply.
  • Build errors after adding @theme. Make sure your syntax is correct: each variable ends with a semicolon, and the block is closed. Also, ensure you have the latest version of @tailwindcss/postcss or the Vite plugin.

Frequently Asked Questions

Can I still use tailwind.config.js in v4?

Yes, but it’s now mainly for content paths and plugins. For theme customization, the recommended way is the @theme directive in CSS.

How do I add a color with a name like brand?

Define --color-brand: #hex; inside @theme. Then use bg-brand, text-brand, etc.

Does @theme work with the Play CDN?

The Play CDN supports a tailwind.config option in the script tag, but the @theme CSS directive may not work reliably. For production, use the build tool.

Can I use CSS variables that change dynamically (e.g., for theming)?

Yes. Define the color variable in @theme and then override it in a selector like .dark or [data-theme="dark"]. Tailwind utilities will pick up the new value.

How do I create a color scale with 10 shades?

Define 10 variables from --color-primary-50 to --color-primary-900. You can use a tool like Tailwind’s color palette generator to get the hex values.

Why does my custom color not work with bg-opacity-*?

In v4, opacity modifiers are used like bg-primary-500/50 instead of bg-opacity-50. If you use the old syntax, it won’t work. Also, the color must be defined as a --color-* variable.

Related

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →