bg-muted not working in Tailwind CSS v4 with custom CSS variables

Question

I'm using Tailwind CSS v4 with a custom theme that defines --muted using CSS variables. However, the utility class bg-muted does not seem to apply any background color when used in my components.

What I Have Tried:

tailwind.config.ts :

import type { Config } from "tailwindcss";

const config: Config = {
  darkMode: "class",
  content: ["./index.html", "./src/**/*.{js,ts,jsx,tsx}"],
  theme: {
    extend: {
      colors: {
        muted: "hsl(var(--muted))",
        "muted-foreground": "hsl(var(--muted-foreground))",
        // other custom colors...
      },
    },
  },
  plugins: [],
};
export default config;

Global CSS (e.g. index.css or globals.css):

@import "tailwindcss";

@layer base {
  :root {
    --muted: 0 0% 96.1%;
    --muted-foreground: 0 0% 45.1%;
  }
  .dark {
    --muted: 0 0% 14.9%;
    --muted-foreground: 0 0% 63.9%;
  }
}

JSX Usage:

<div className="bg-muted p-4 text-black">Test</div>

Observed Behavior:

The class bg-muted shows up in the HTML.
But it does not apply any visible background color.
No errors are thrown.

Things I’ve Checked:

Tailwind classes are being applied.
The custom property --muted is defined under :root.
The file using bg-muted is inside src/ and covered by content.
Other Tailwind classes (e.g. bg-red-500) work fine.
Tried switching to muted: { DEFAULT: "hsl(var(--muted))" } — no change.

Question:

Why is bg-muted not applying any color in this setup? Is there something I'm missing with CSS variables + Tailwind v4?

rozsazoltan · Accepted Answer · 2025-08-04 18:21:08Z

Starting with TailwindCSS v4, there is no tailwind.config.js.

What's breaking changes from v4? - StackOverflow
New CSS-first configuration option in v4 - StackOverflow

Instead, use the CSS-first configuration approach.

How to use custom color themes in TailwindCSS v4 - StackOverflow
What are theme variables? - TailwindCSS v4 Docs
Toggling dark mode manually - TailwindCSS v4 Docs

@import "tailwindcss";

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

@layer base {
  :root {
    --muted: 0 0% 96.1%;
    --muted-foreground: 0 0% 45.1%;
  }
  .dark {
    --muted: 0 0% 14.9%;
    --muted-foreground: 0 0% 63.9%;
  }
}

@theme inline {
  --color-muted: hsl(var(--muted));
  --color-muted-foreground: hsl(var(--muted-foreground));
}

https://play.tailwindcss.com/xPkokCcN6S?file=css

Or, if you no longer want to reference global variables in the new CSS-first configuration, keep in mind that @theme already declares global variables, which you can override in dark mode.

How to override theme variables in TailwindCSS v4 - @theme vs @layer theme vs :root - StackOverflow
Should I use @theme or @theme inline? - StackOverflow
When should I use * and when should I use :root, :host as the parent selector? - StackOverflow

@import "tailwindcss";

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

@theme {
  --color-muted: hsl(0 0% 96.1%);
  --color-muted-foreground: hsl(0 0% 45.1%);
}

@layer theme {
  :root, :host {
    @variant dark {
      --color-muted: hsl(0 0% 14.9%);
      --color-muted-foreground: hsl(0 0% 63.9%);
    }
  }
}

https://play.tailwindcss.com/dt9yiqdfmr?file=css

Collectives™ on Stack Overflow

bg-muted not working in Tailwind CSS v4 with custom CSS variables

What I Have Tried:

Observed Behavior:

Things I’ve Checked:

Question:

1 Answer 1

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

What I Have Tried:

Observed Behavior:

Things I’ve Checked:

Question:

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related