Tailwind CSS + UI libraries = no conflicts 🚀

What

Tailwind CSS plugin

Why

To avoid style conflicts (CSS collisions/interference side effects) when using Tailwind CSS with other UI libraries like Antd, Vuetify etc.

How

This plugin limits the scope of Tailwind's opinionated preflight styles to a customizable CSS selector. So you can control exactly where in the DOM to apply these base styles — usually your own components, not third-party ones.

Version 4 is here 🎉

Migrate from v3

Looking for the v3 documentation? v3 README

Version 4 is built for TailwindCSS v4 and uses the new CSS-first @plugin API — no JavaScript config needed.

Key changes from v3:

• Configure via @plugin in your CSS file, not tailwind.config.js
• No JS imports required
• Simpler option syntax using CSS property values

❤️ If you'd like to say thanks, buy me a coffee

Support/contact tiny website

Discord server for any discussions/questions/ideas/proposals — feel free to join.

Strategies overview

Two isolation strategies are available, covering 99% of cases:

| Strategy | Description | |:-----------------------------------------------------------------------------------------:| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | isolation-strategy: inside | Everything is protected from preflight styles, except the specified Tailwind root(s).Use it when all your Tailwind-powered content lives inside some root container. | | isolation-strategy: outside | Protects specific root(s) from preflight styles — Tailwind is everywhere outside.Use it when Tailwind is everywhere, but you want to exclude some part of the DOM from preflight. |

Quick Start

1. Install

npm i -D tailwindcss-scoped-preflight

2. Replace your Tailwind import

Most projects start with a single import:

@import "tailwindcss";

This includes Tailwind's global preflight (CSS reset) — which is exactly what this plugin replaces with a scoped version. To avoid having both global and scoped preflight in your CSS, replace the single import with granular ones that skip preflight:

@import "tailwindcss/theme";
@import "tailwindcss/utilities";

Why not @import "tailwindcss"? It bundles preflight that applies to *, html, body globally. With this plugin you want preflight scoped to your selector — having both defeats the purpose.

3. Add @plugin to your CSS file

3.1 Lock Tailwind preflight inside a container

Use isolation-strategy: inside when all your Tailwind-powered content is under a single root element (like .twp). Preflight styles will only apply within that container.

/* input.css */
@import "tailwindcss/theme";
@import "tailwindcss/utilities";

@plugin "tailwindcss-scoped-preflight" {
  isolation-strategy: inside;
  selector: .twp;
}

With an exclusion zone (to protect third-party markup nested under .twp):

@plugin "tailwindcss-scoped-preflight" {
  isolation-strategy: inside;
  selector: .twp;
  except: .no-twp;
}

| Option | Value | Description | |:------------------------:| ------------------------------ | ------------------------------------------------------------------------------------------------------------ | | isolation-strategy | inside | Required. Activates the inside-container isolation mode. | | selector | CSS selector (or comma-list) | Required. The container(s) where Tailwind content lives. e.g. .twp or .twp, [twp] | | except (optional) | CSS selector | Excludes nested elements from preflight. Useful for third-party markup under .twp. | | root-styles (optional) | move to container (default) | Moves root styles (html/body/:host) to the container selector. | | | add :where | Keeps root styles on root selectors but wraps them with :where so only matching items are affected. | | ignore (optional) | Comma-separated CSS selectors | Keeps these preflight selectors untouched (skipped by the isolation strategy). e.g. html, :host, * | | remove (optional) | Comma-separated CSS selectors | Removes preflight styles for these selectors entirely. e.g. body, :before, :after |

3.2 Exclude a container from Tailwind preflight

Use isolation-strategy: outside when Tailwind is used everywhere, but you want one section of the page to be unaffected by preflight (e.g. a legacy widget or iframe content).

/* input.css */
@import "tailwindcss/theme";
@import "tailwindcss/utilities";

@plugin "tailwindcss-scoped-preflight" {
  isolation-strategy: outside;
  selector: .no-twp;
}

With a plus selector (to re-enable preflight for Tailwind components nested inside the excluded zone):

@plugin "tailwindcss-scoped-preflight" {
  isolation-strategy: outside;
  selector: .no-twp;
  plus: .twp;
}

| Option | Value | Description | |:--------------------:| ----------------------------- | --------------------------------------------------------------------------------------------------------------- | | isolation-strategy | outside | Required. Activates the outside-container isolation mode. | | selector | CSS selector (or comma-list) | Required. The container(s) to protect from preflight. e.g. .no-twp | | plus (optional) | CSS selector | Re-enables preflight for Tailwind components nested inside the excluded zone. e.g. .twp | | ignore (optional) | Comma-separated CSS selectors | Keeps these preflight selectors untouched (skipped by the isolation strategy). | | remove (optional) | Comma-separated CSS selectors | Removes preflight styles for these selectors entirely. |

Choosing a good selector

Use a dedicated plain class name (.twp, .no-twp) or a data attribute ([data-twp]) as your container selector. Avoid selectors that contain colons (like Tailwind modifier syntax .xl:some-class) — they require CSS escaping (\.xl\:some-class) and add unnecessary complexity.

4. Use the selector in your DOM

export function MyApp({ children }: PropsWithChildren) {
  return <div className={'twp'}>{children}</div>;
}

Configuration examples

Using multiple selectors

@plugin "tailwindcss-scoped-preflight" {
  isolation-strategy: inside;
  selector: .twp, [twp];
}

Although all strategies accept multiple selectors, it's recommended to use one short selector to avoid CSS bloat — selectors repeat many times in the generated CSS.

Keeping some preflight styles unaffected

Use ignore to pass certain preflight selectors through without modification:

@plugin "tailwindcss-scoped-preflight" {
  isolation-strategy: inside;
  selector: .twp;
  ignore: html, :host, *;
}

Removing preflight styles by selector

Use remove to strip preflight styles for specific selectors entirely:

@plugin "tailwindcss-scoped-preflight" {
  isolation-strategy: inside;
  selector: .twp;
  remove: body, :before, :after;
}

Still using JS config?

TailwindCSS v4 still supports JavaScript configuration via @config, though it's deprecated in favor of CSS-first configuration. This plugin works with both approaches — choose one, not both:

| Approach | How | Recommended? | |----------|-----|:------------:| | CSS-first (@plugin) | Configure in your .css file | ✅ Yes | | JS config (@config) | Configure in tailwind.config.js | For SCSS or gradual migration |

Using @config with this plugin

// tailwind.config.js
import scopedPreflightStyles from 'tailwindcss-scoped-preflight';

export default {
  plugins: [
    scopedPreflightStyles({
      isolationStrategy: 'inside',
      selector: '.twp',
    }),
  ],
};

/* input.css */
@import "tailwindcss/theme";
@import "tailwindcss/utilities";
@config "./tailwind.config.js";

All options from the inside and outside strategy tables work the same way — pass them as object properties instead of CSS declarations.

Important: Even with @config, use the new v4 string-based options — not the v3 function-based API. See the migration guide for the full mapping.

Using with SCSS/Sass

Sass preprocessors parse .scss files before TailwindCSS sees them. The @plugin block syntax contains values like selector: .twp; that Sass misinterprets — it sees .twp as the start of a decimal number and fails:

Error: Expected digit.
  ╷
  │   selector: .twp;
  │              ^
  ╵

Option A: Separate CSS file (recommended)

Move the @plugin directive and Tailwind imports to a plain .css file, then import it from your SCSS:

/* tailwind.css */
@import "tailwindcss/theme";
@import "tailwindcss/utilities";

@plugin "tailwindcss-scoped-preflight" {
  isolation-strategy: inside;
  selector: .twp;
}

/* globals.scss */
@use "tailwind.css";

// your SCSS styles

Option B: Use @config with JS config

Use @config to configure the plugin in JavaScript — Sass won't try to parse the plugin options:

/* globals.scss */
@import "tailwindcss/theme";
@import "tailwindcss/utilities";
@config "./tailwind.config.js";

// your SCSS styles

See the @config section above for the tailwind.config.js example.

Migration guide (v3 → v4)

TailwindCSS v4 replaced JavaScript config files with a CSS-first API. This plugin follows the same shift — configure via @plugin in CSS (recommended) or via @config with updated options.

Quick reference

| v3 (tailwind.config.js) | v4 (input.css) | | ----------------------------------------------------------------- |------------------------------------------------------------------------| | plugins: [scopedPreflightStyles({ ... })] | @plugin "tailwindcss-scoped-preflight" { ... } | | import { scopedPreflightStyles, isolateInsideOfContainer } | No JS import needed (or import scopedPreflightStyles with @config) | | isolationStrategy: isolateInsideOfContainer('.twp') | isolation-strategy: inside; selector: .twp; | | isolationStrategy: isolateOutsideOfContainer('.no-twp') | isolation-strategy: outside; selector: .no-twp; | | ['.twp', '[twp]'] (array) | selector: .twp, [twp]; (comma-separated) | | { except: '.no-twp' } | except: .no-twp; | | { plus: '.twp' } | plus: .twp; | | { ignore: ['html', ':host'] } | ignore: html, :host; | | { remove: ['body'] } | remove: body; | | modifyPreflightStyles: { ... } | Not available in v4 | | Custom isolationStrategy function | Not available in v4 | | isolateForComponents | Not available in v4 — use inside strategy instead |

Before/after: inside strategy

v3 (tailwind.config.js):

import { scopedPreflightStyles, isolateInsideOfContainer } from 'tailwindcss-scoped-preflight';

export default {
  plugins: [
    scopedPreflightStyles({
      isolationStrategy: isolateInsideOfContainer('.twp', {
        except: '.no-twp',
      }),
    }),
  ],
};

v4 (input.css):

@import "tailwindcss/theme";
@import "tailwindcss/utilities";

@plugin "tailwindcss-scoped-preflight" {
  isolation-strategy: inside;
  selector: .twp;
  except: .no-twp;
}

Before/after: outside strategy

v3 (tailwind.config.js):

import { scopedPreflightStyles, isolateOutsideOfContainer } from 'tailwindcss-scoped-preflight';

export default {
  plugins: [
    scopedPreflightStyles({
      isolationStrategy: isolateOutsideOfContainer('.no-twp', {
        plus: '.twp',
      }),
    }),
  ],
};

v4 (input.css):

@import "tailwindcss/theme";
@import "tailwindcss/utilities";

@plugin "tailwindcss-scoped-preflight" {
  isolation-strategy: outside;
  selector: .no-twp;
  plus: .twp;
}

Before/after: multiple selectors

v3 (tailwind.config.js):

scopedPreflightStyles({
  isolationStrategy: isolateInsideOfContainer(['.twp', '[twp]']),
})

v4 (input.css):

@plugin "tailwindcss-scoped-preflight" {
  isolation-strategy: inside;
  selector: .twp, [twp];
}

Dropped features

The following v3 features are not available in v4. TailwindCSS 4 moved away from JavaScript config entirely, so any feature that required a JS callback or JS-level hook cannot be supported.

| Feature | v3 Usage | Why removed | |-------------------------------------|---------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------| | modifyPreflightStyles | Object or function callback to alter individual CSS declarations | TW4 has no hook mechanism for JS-based style modification — all config is CSS strings | | Custom isolationStrategy function | isolationStrategy: ({ ruleSelector }) => string | @plugin CSS blocks only accept string scalar values, not functions | | isolateForComponents | Named export, was already deprecated in v3 | Deprecated in v3; removed in v4. Use isolation-strategy: inside with root-styles: add :where for the same effect | | Named strategy imports | import { isolateInsideOfContainer } from 'tailwindcss-scoped-preflight' | No JS config to import into — use @plugin directive or default import with @config |