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.cssorapp.css). - Basic familiarity with CSS custom properties (variables).
Step-by-Step
- Open your main CSS file. This is the file where you import Tailwind. It typically starts with
@import "tailwindcss";. - Add an
@themeblock after the import. The@themedirective is where you define design tokens like colors, fonts, and spacing. It replaces thethemesection of the old config file. - 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 namedbrand, write:@theme { --color-brand: #3490dc; }Now you can use
bg-brand,text-brand,border-brand, etc. - 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-500ortext-primary-100. - Use the
@themeblock with a custom name (optional). You can also namespace your colors, e.g.,--color-company-blue: #0055ff;. This generates classes likebg-company-blue. - 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);. - Rebuild your CSS. If you’re using a build step (Vite, PostCSS), run your build command (
npm run buildornpm run dev). Tailwind v4 scans your source files and generates the utilities on-demand. - Verify in your HTML. Add a class like
bg-brandortext-primary-500to an element and check that the color applies.
Common Mistakes
- Using the old config file. In v4,
tailwind.config.jsis 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
@themeinside a media query or after other CSS rules.@themeshould be at the top level of your stylesheet, ideally right after the import. - Using hex values without the hash. Always include the
#or usergb()/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.cssand import it into your main CSS file to keep things organized. - Use the
@themeblock for other tokens too. You can define spacing, fonts, and more. For example,--font-display: "Inter", sans-serif;gives youfont-display. - Leverage CSS variables for dynamic themes. You can override the variables in a
data-themeattribute 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@thememight not work; use the CDN’stailwind.configoption instead. - Classes like
bg-brandare 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@sourcedirective. - 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-redwould override the defaultredpalette. - 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/postcssor 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
- Set a Google Play Budget & Stop Accidental Purchases
- Destiny 2 Error Code Anteater: Fixes & Causes
- View Android Photos on Chromebook: Step-by-Step
- Fix Windows Could Not Prepare the Computer to Boot
- Windows 11 Security Settings: Best Config Guide
- Install Custom Recovery on Samsung Galaxy Trend