Tailwind v4 has no important option support

[martin-dimi]

I tried updating tailwind to v4 today, but I noticed there is no support for the important config. Specifically this config.

In my case, I have a chrome extension which injects dom onto some pages. I use the important cause like this "important": "#my-extension" which forces all tailwind classes to have higher specificity over the original website's css.

[wongjn]

You'd replace the @import "tailwindcss"; with:

@layer theme, base, components, utilities;

@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/preflight.css" layer(base);

@theme {
  /* ... */
}

@layer utilities {
  #my-extension {
    @tailwind utilities;
  }
}

[wongjn]

Will i break something or lose funcitonality in tailwind if I remove all the layers?

You may do. Tailwind has been built with the intention that layers are used.

can I scope all the other tailwind styles (theme, base) as well?

You can try it, but I'm not sure that works. Also as an aside, the base layer is different to preflight.

[martin-dimi]

Appologies, I meant preflight (have edited my comment). I need to have that scoped too as it affects the origin site, otherwise.
Having the import within the id selector seems to work (honestly, I didn't expect it to work..).

You may do. Tailwind has been built with the intention that layers are used.

Interesting. Is there an official solution / planned feature to cover such use cases? Again, that's when tailwind is used a on scoped section of an existing site. To recap:

1. Tailwind styles need to be scoped. (so they don't affect the whole site, e.g. no margins with prelight)
2. Tailwind styles need to take precedence over the global (non-layerd) styles.

I've tried using shadow dom for this, but unfortunately that doesn't work either (suspect its because the theme is using :root
which doesn't play nicely with shadow dom)

[wongjn]

Is there an official solution / planned feature to cover such use cases?

Not that I've seen.

[michaeltravan]

Hello @wongjn and @martin-dimi, apologies for resuming this thread but this is the closest I could find to my current situation. I'm using tailwind cli version 4 on a WordPress plugin, which as you surely know, has various scope-related issues. I thought I might add my experience.

What I'm trying to do is keeping all my utilities under a common Id (say #plugin) and following @wongjn directions I managed to do that by removing @layer utilities {}. But preflight styles are still leaking on the WordPress backend, causing various layout issues. I could of course remove preflight styles but since they're there for a reason, I'd like to keep them and scope them as well under the same Id. This is where I get lost. I've tried something like this, but it doesn't work.

@theme {
 ...
}

#youmini-panel {
  @import "tailwindcss/theme.css";
  @import "tailwindcss/preflight.css";

  @tailwind utilities;
}

Have you folks come up to anything working? Thanks!

[wongjn]

For scoping preflight.css like that, you'd need to reintroduce this rule, since its selectors are for html, :host:

tailwindcss/packages/tailwindcss/preflight.css

Lines 28 to 46 in c45616f

	html,
	:host {
	line-height: 1.5; /* 1 */
	-webkit-text-size-adjust: 100%; /* 2 */
	tab-size: 4; /* 3 */
	font-family: --theme(
	--default-font-family,
	ui-sans-serif,
	system-ui,
	sans-serif,
	'Apple Color Emoji',
	'Segoe UI Emoji',
	'Segoe UI Symbol',
	'Noto Color Emoji'
	); /* 4 */
	font-feature-settings: --theme(--default-font-feature-settings, normal); /* 5 */
	font-variation-settings: --theme(--default-font-variation-settings, normal); /* 6 */
	-webkit-tap-highlight-color: transparent; /* 7 */
	}

Probably copy-pasting is the easiest way.

For theme.css, I don't believe there is any sure fire way in Tailwind alone, since its content is generated dynamically with the :root, :host selector. You'd need some post processor on the resultant CSS to change the selector for this rule.

https://play.tailwindcss.com/7be8xnDVt3?file=css

[ouweiya]

After several attempts, I discovered that using the postcss-nested plugin makes it easy to solve this problem.

.app {
    @import 'tailwindcss' source('../src');
}

Compiled result:

@layer theme, base, components, utilities;
@layer theme {
  .app :root, .app :host {
    --font-sans: ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji",
      "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
      ...
  }
}

@layer base {
  .app *, .app ::after, .app ::before, .app ::backdrop, .app ::file-selector-button {
    box-sizing: border-box;
    ...
  }

  .app html, .app :host {
    line-height: 1.5;
    -webkit-text-size-adjust: 100%;
    ...
  }
  ...
}

@layer utilities {
  .app .text-red-500 {
    color: var(--color-red-500);
  }
  ...
}

Soon, I realized that selectors like .app :root and .app html don't actually exist. As a result, the defined CSS variables and properties had no effect. I initially planned to write a simple plugin to replace html and :root selectors with .app, but I discovered that the community already offers a well-made plugin: postcss-prefix-selector.

In the end, I didn’t need to modify the input.css file at all — simply adding the plugin resolved the problem.

My configuration:

/* input.css */
@import 'tailwindcss' source('../src');

/* postcss.config.mjs */
export default {
    plugins: {
        '@tailwindcss/postcss': {},
        'postcss-nested': {},
        'postcss-prefix-selector': { prefix: '.app' },
    },
}

The postcss-prefix-selector plugin adds the specified prefix and also replaces html, body, and :root selectors with .app.

If you don't need to transform CSS Nesting syntax for legacy browser compatibility, you can remove the postcss-nested plugin and instead add a custom transform function. This function will apply the prefix only to the top-level selectors, preserving the nested structure.

'postcss-prefix-selector': {
    prefix: '.app',
    exclude: [/^\s*\.app(?:\b|[\s.#[:])/],
    transform: (prefix, selector, prefixedSelector, filePath, rule) => {
        // Replace ':root', 'body', and 'html' with .app
        if ([':root', 'body', 'html'].some(globalSel => selector.startsWith(globalSel))) {
            return selector.replace(/(html\s+body|:root\s+body|html|:root|body)/gm, prefix);
        }

        // Skip nested rules — only apply prefix to root-level rules
        if (rule.parent && rule.parent.type === 'rule') {
            return selector;
        }

        // Apply prefix to top-level selector only
        return prefixedSelector;
    },
}

Compiled result:

.app .a {
  .b {  
    ...
  } 
}

One more important note: if you're using multiple PostCSS plugins, you might encounter an issue where the prefix is added multiple times.

For example:

.app .app .a {
    ...
}

To prevent this, you should add the exclude option. This option ensures that selectors which already have the prefix are skipped.

'postcss-prefix-selector': {
    prefix: '.app',
    exclude: [/^\s*\.app(?:\b|[\s.#[:])/],
}

As I progressed with the migration to Tailwind v4, I encountered several unexpected issues.

Did you think adding a prefix would solve all scoping problems? I used to think the same. However, v4 introduced the @layer feature, which brought new complications.

Example:

<body class="app">
    <div class="bg-green-500">Hello</div>
</body>

@layer utilities {
  .app .bg-green-500 {
    background-color: var(--color-green-500);
  }
}

div {
  background: red;
}

In past experience, the selector .app .bg-green-500 had higher specificity than div, so the background should appear green. But with @layer, the background is now red.
The reason is that @layer introduces a new behavior: when used, the browser ignores selector specificity and instead respects the order in which @layer blocks are declared.
Any rules not inside an @layer block are considered to be in the browser’s implicit layer, which always comes last and thus wins in conflicts.
The final cascade order becomes: @layer theme, base, components, utilities, implicit layer.

There are two ways to resolve this issue:

• Remove the layers
• Add important (not recommended)

Removing layers (layer(xxx)):

@import 'tailwindcss/theme.css' source('../src');
@import 'tailwindcss/preflight.css' source('../src');
@import 'tailwindcss/utilities.css' source('../src');

See also:
[v4] Will there be a way to opt out of native cascade layers?

Using important:

@import "tailwindcss" important;

There are a few subtle changes in v4 that are not clearly highlighted in the documentation:

• Tailwind v4 uses @property to define CSS variables, and sets inherits: false. In v3, colors might have been inherited by default — this is no longer the case.
• The properties scale, translate, and rotate are no longer part of transform: .... Instead, they are individual properties. If you previously used transition-[transform], you now need to change it to transition-[translate], etc.
• Theme variables for background images now use the namespace --background-image-*.
• In v3, theme variables were attached directly to class names; in v4, they're attached to :root. This changes how variables are resolved.

<div class="bg-me [--bg:red]">Hello</div>

v3 theme config:

export default {
  theme: {
    extend: {
      colors: {
        me: 'var(--bg)',
      },
    },
  },
}

v4 theme config:

@theme {
   --color-me: var(--bg);
}

v3 output:

.bg-me {
  background-color: var(--bg);
}
.\[--bg\:red\] {
  --bg: red;
}

v4 output:

@layer theme, base, components, utilities;
@layer theme {
  :root, :host {
    --color-me: var(--bg);
  }
}
@layer utilities {
  .bg-me {
    background-color: var(--color-me);
  }
  .\[--bg\:red\] {
    --bg: red;
  }
}

In v4, the variable --bg defined on the element itself is no longer found due to the variable being resolved from :root.

v3 tailwind play https://play.tailwindcss.com/shIRdFxzH3
v4 tailwind play https://play.tailwindcss.com/ahx00gznFV

Performance Warning

@import 'tailwindcss' source('../src');
At first glance, specifying the file detection scope with source('../src') seems elegant, but it actually introduces performance issues. This directive causes Tailwind to scan nearly every file in the src directory, including unrelated files like JSON and Markdown.
Tailwind will spend significant time extracting potential class names from these irrelevant files, which can drastically slow down the build process.

Therefore, it's important to narrow the file scope as precisely as possible.

Here’s my configuration:

@import 'tailwindcss/theme.css' source(none);
@import 'tailwindcss/preflight.css' source(none);
@import 'tailwindcss/utilities.css' source(none);

@source "./{components,views}/**/*.{tsx,svg}";
@source "./App.tsx";
@source not "./{components,views}/**/index.tsx";

Note: Adding source(none) after each @import is not mindless repetition—it’s intentional.
If omitted, it may cause the source(none) directive to stop working as expected.

[StreetXHasu]

Were you sent from heaven? This helped a lot — exactly my case

[cyucelen]

Godsent. Absolute legend 🙌

[manudoni-hubcore]

Thank you so much!
I would like to point out that for setting general styles such as div { background: ...} you could just add it to the base layer, this way the classbg-green-500 will have higher specificity

@import 'tailwindcss'
@layer base {
  div {
    background: red;
  }
}

[ouweiya]

Thank you so much! I would like to point out that for setting general styles such as div { background: ...} you could just add it to the base layer, this way the classbg-green-500 will have higher specificity

@import 'tailwindcss'
@layer base {
  div {
    background: red;
  }
}

If you are developing a Chrome extension, you won’t be able to control other stylesheets, so you can only override them by using higher specificity.

[estevan-ulian]

Thank you very much!

Here is my contribution for those using Vite. Just install postcss-prefix-selector and autoprefixer:

npm install --save-dev postcss-prefix-selector @types/postcss-prefix-selector autoprefixer

And in the file vite.config.ts:

import prefixer from 'postcss-prefix-selector';
import autoprefixer from 'autoprefixer';

export default defineConfig({
...
plugins: [..., tailwindcss()],
css: {
    postcss: {
      plugins: [
        prefixer({
          prefix: "#my-app-prefix",
        }),
        autoprefixer({}),
      ],
    },
  },
...
});

Ref: https://www.npmjs.com/package/postcss-prefix-selector#usage-with-vite