How to use tailwind v4 with Hero UI

[chirag0055]

I installed tailwind v4 but it didn't create tailwind.config.jx file and also 'npx tailwindcss init-p' is also not working

[wongjn]

The init command no longer exists in v4. Consider checking the installation documentation that is most relevant to your project to integrate Tailwind v4.

[chirag0055]

I installed the tailwind v4, now I have to use Hero UI but its plugin is to be written in "tailwind.config.js" which is not available

[wongjn]

You can include a legacy tailwind.config.js via the @config directive.

[leetcow]

that doesn't work: error: addUtilities({ ':root' : … })defines an invalid utility selector. Utilities must be a single class name and start with a lowercase letter, eg..scrollbar-none.

[abhishekml121]

@leetcow I also upgraded to tailwindcss4 and added 3 lines at the top of the global.css file:
@import 'tailwindcss'; @source '../node_modules/@heroui/theme/dist/**/*.{js,ts,jsx,tsx}'; @custom-variant dark (&:is(.dark *));

This the current view : https://streamable.com/naexgk
As you can see in the shared video (above link), button styles (bg-color, border-radius etc) are NOT working.

I removed the @config for tailwind.config.js from global.css file because it started to giving me the same error which you got.

[admin-wavedropper]

that doesn't work: error: addUtilities({ ':root' : … })defines an invalid utility selector. Utilities must be a single class name and start with a lowercase letter, eg..scrollbar-none.

I was having the same issues. The fix was to create a custom plugin wrapper that intercepts when HeroUI tries to add :root selectors as utilities (which Tailwind v4 doesn't allow anymore):

//custom-heroui-plugin.js

import { heroui } from "@heroui/theme";

export function customHeroui() {

  return (tailwindConfig) => {

    const heroPlugin = heroui();
    
    return (api) => {
      const originalAddUtilities = api.addUtilities;
      
      // Fix the :root selector issue
      api.addUtilities = (utilities, options) => {
        const rootStuff = {};
        const normalStuff = {};
        
        Object.entries(utilities).forEach(([key, value]) => {
          if (key === ':root' || key.startsWith(':root')) {
            rootStuff[key] = value;
          } else {
            normalStuff[key] = value;
          }
        });
        
        if (Object.keys(rootStuff).length > 0) {
          api.addBase(rootStuff); // Use addBase instead for :root
        }
        
        if (Object.keys(normalStuff).length > 0) {
          originalAddUtilities(normalStuff, options);
        }
      };
      
      return heroPlugin(api);
    };
  };
}

Then just used this custom wrapper in tailwind config:

import { customHeroui } from "./custom-heroui-plugin";

export default {
  // your other config...
  plugins: [customHeroui()],
};

[rozsazoltan]

• Problem installing TailwindCSS with Vite, after "npx tailwindcss init -p" command - StackOverflow

[abdul99ahad]

HeroUI does not yet support Tailwind CSS v4 yet. (Reference: GitHub Issue)

[amirhd-com]

when HeroUI support tailwindcss v4?!

[jackgray-nycbs]

Thanks for your reply. I guess I'm back at square 1 as to why my migration is failing for next.js 15+, following the guide as closely as I can. I will direct further inquiries to newer threads. although i do find it confusing that this template claims to use v4 but uses heroui v2.2 , and it has been updated in the past 24 hours.... https://github.com/heroui-inc/next-app-template/tree/main

I am still unable to get the styles to generate on build following the official guide or this template.

[rozsazoltan]

@jackgray-nycbs Instead of using postcss.config.js, the template should use postcss.config.mjs for TailwindCSS v4 - I believe this is a mistake.

The tailwind.config.js file is no longer necessary in v4. It looks like the template tries to use @config, but it contains several inaccurate and/or outdated properties. It seems to be merged a bit hastily.

I've added my questions to the PR you mentioned:

• feat: tailwindcss v4 support heroui-inc/next-app-template#38 (comment)

[jackgray-nycbs]

does next.js.config need to be modified as in the vite block? Or should I wait a few weeks for the kinks to be hashed out? I am just not finding any one document that doesn't conflict with another that i can follow to get to a working next.js set-up, and i feel like i'm circling the right permutation but can't seem to get them all right at the same time.

[rozsazoltan]

Currently, the main point of conflict is the HeroUI documentation. I've left my questions in the PR. Next.js works perfectly with TailwindCSS v4. I believe that by following the steps I included in the PR, you can successfully integrate HeroUI into a Next.js + TailwindCSS v4 app created with create-next-app, and that the issue lies solely with the HeroUI template.

Step-1 Next.js official template with TailwindCSS v4:

• https://github.com/vercel/next.js/tree/canary/packages/create-next-app/templates/app-tw/ts
• https://nextjs.org/docs/app/api-reference/cli/create-next-app#reference

(or) Manually migration guides:

• https://nextjs.org/docs/app/guides/tailwind-css
• https://tailwindcss.com/docs/installation/framework-guides/nextjs
• How to install TailwindCSS v4 with Next.js

Step-2 Manually HeroUI installation:

• How to install HeroUI with TailwindCSS v4

So Steps 1 and 2 combined would look like this - I would do it this way to create a new Next.js + TailwindCSS v4 + HeroUI v2.8 project:

Install Next.js official app template with TailwindCSS v4, TypeScript and ESLint support

npx create-next-app@latest my-project --tailwind --typescript --eslint --app
cd my-project

Install HeroUI

npm install @heroui/react@latest

Create app/hero.ts (heroui-inc/next-app-template#38 (comment))

// hero.ts
import { heroui } from "@heroui/react";
export default heroui();

Change app/globals.css

@import "tailwindcss";
@plugin './hero.ts';

/* ./app/../node_modules */
@source '../node_modules/@heroui/theme/dist/**/*.{js,ts,jsx,tsx}';

@custom-variant dark (&:is(.dark *));

@theme inline {
  --font-sans: var(--font-sans);
  --font-mono: var(--font-mono);
}

/* You can keep or delete the previous contents of the file as you prefer. */
:root {
  --background: #ffffff;
  --foreground: #171717;
}

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --font-sans: var(--font-geist-sans);
  --font-mono: var(--font-geist-mono);
}

@media (prefers-color-scheme: dark) {
  :root {
    --background: #0a0a0a;
    --foreground: #ededed;
  }
}

body {
  background: var(--background);
  color: var(--foreground);
  font-family: Arial, Helvetica, sans-serif;
}

[jackgray-nycbs]

It's working now! I cannot fully express my gratitude for this!!

I was really nearing the end of my rope haha, but following this brought me and my app back to life!

Thank you so so much for your immediate attention and getting me through it!

[rozsazoltan]

After the merge of HeroUI PR #4656, support for TailwindCSS v4 became available with the release of the v2.8.0 stable/latest (non-beta) version on 2025-07-15.