Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

hover: on your own CSS class does nothing in Tailwind

Errorhover:my-class has no effect

Short answer

Tailwind only attaches variants such as hover: to utilities it knows about. A plain class you wrote in a CSS file is not one. In v4 declare it with @utility; in v3 put it inside @layer components or @layer utilities. Also remember that in v4 hover only fires on devices whose main input can hover.

  • Applies to Next.js 15, Next.js 16, Tailwind CSS 3.4, Tailwind CSS 4
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    See how the class is defined and which Tailwind version you run.

    npm ls tailwindcss
    grep -rn "@utility\|@layer" app/globals.css
  2. 2Match what you see, then jump to its fix

    1. 1The project uses @import "tailwindcss" and the class is written as .my-class { ... } outside any directive.Tailwind v4: the class is plain CSS, not a registered utilityFix
    2. 2The project uses @tailwind directives and the class is not wrapped in @layer.Tailwind v3: the class is outside a layerFix
    3. 3Hover works with a mouse but not when you test on a phone or in a touch emulator.Tailwind v4: hover is skipped on touch devicesFix

What does the error look like?

  • hover:my-class has no effect
  • Trying to apply hover: to a Tailwind CSS custom-class I made, but it doesn't seems to work

Cause 1 of 3

Tailwind v4: the class is plain CSS, not a registered utility

1Check

Look for @utility in the stylesheet. Custom utilities declared with it work with variants such as hover, focus and lg.

grep -n "my-class" app/globals.css

2Fix

Rewrite the rule with @utility, using the name without the dot. Nested rules go inside it.

/* app/globals.css */
@utility my-class {
  text-decoration: underline;
}

3Verify

Use hover:my-class in the markup and hover over the element.

<a class="hover:my-class">Link</a>

Confirmed by tailwindcss.com

Did this fix it?

Cause 2 of 3

Tailwind v3: the class is outside a layer

1Check

In v3, styles added with @layer support the modifier syntax for things like hover states.

grep -n "@layer" styles/globals.css app/globals.css

2Fix

Wrap the class in @layer utilities (or components) in the global stylesheet.

@layer utilities {
  .my-class {
    text-decoration: underline;
  }
}

3Verify

Restart the dev server and try hover:my-class again.

npm run dev

Confirmed by v3.tailwindcss.com

Did this fix it?

Cause 3 of 3

Tailwind v4: hover is skipped on touch devices

1Check

In v4 the hover variant only applies when the primary input device supports hover.

window.matchMedia('(hover: hover)').matches

2Fix

Treat hover as an enhancement. If you rely on the old behaviour, override the variant with your own.

/* app/globals.css */
@custom-variant hover (&:hover);

3Verify

Rebuild and tap the element on a touch device.

npm run dev

Confirmed by tailwindcss.com

Did this fix it?

How do I stop it coming back?

  • Keep all custom classes in one global stylesheet and declare each with @utility (v4) or @layer (v3).
  • Prefer variant-friendly utilities over bare classes for anything that needs hover, focus or breakpoints.
  • Do not depend on hover for touch users.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Web apps

Hydration failed after adding next-themes dark mode

Console reports a server and client mismatch on the html element

next-themes changes the html element and knows the theme only in the browser, so server HTML and client HTML differ.

3 causes, each with a fix

Web apps

Next.js fails with Cannot find module 'tailwindcss'

Error: Cannot find module 'tailwindcss'

Next.js loads Tailwind through PostCSS, so the error means the package named in postcss.config is not installed where the build runs.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.