A PostCSS plugin that is used to wrap css styles with a css selector to constrain their affect on parent elements in a page.
npm install postcss-prefixwrap



A PostCSS (postcss.org) plugin which prepends a selector to CSS styles to constrain their effect on parent
elements in a page.
| Supports | Versions |
| :------------------------------------------- | :------------------ |
| Bun (bun.sh) | latest |
| Deno (deno.com) | v2 |
| NodeJS (nodejs.org) | v20, v22, v24 |
| PostCSS (postcss.org) | v7, v8 |
> ⚠️ PostCSS v7 support is no longer validated in automated test cases, and will be removed entirely in a future release.
- How to use this plugin?
- What options does it have?
- What problems can it solve?
- How to contribute?
- Is this project secure?
- License
> ⚠️ These instructions are only for this plugin. See the PostCSS (postcss.org) website for framework information.
| Package Manager or Runtime | Command |
| :---------------------------------------------------------------------- | :------------------------------------------------------- |
| Bun (bun.sh) | bun add postcss-prefixwrap --dev --exact |
| Deno (deno.com) | deno add npm:postcss-prefixwrap --dev |
| NPM (npmjs.com) | npm install postcss-prefixwrap --save-dev --save-exact |
| PNPM (pnpm.io) | pnpm add postcss-prefixwrap --save-dev --save-exact |
| Yarn (yarnpkg.com) | yarn add postcss-prefixwrap --dev --exact |
Add to your PostCSS (postcss.org) configuration.
``javascript
const PostCSS = require("gulp-postcss");
const PrefixWrap = require("postcss-prefixwrap");
PostCSS([PrefixWrap(".my-custom-wrap")]);
`
Add the container to your markup.
`html`
View your CSS, now prefix-wrapped.
Before
`css
p {
color: red;
}
body {
font-size: 16px;
}
`
After
`css
.my-custom-wrap p {
color: red;
}
.my-custom-wrap {
font-size: 16px;
}
`
`typescriptignoredSelectors
PrefixWrap(".my-custom-wrap", {
// You may want to exclude some selectors from being prefixed, this is
// enabled using the option.
ignoredSelectors: [":root", "#my-id", /^\.some-(.+)$/],
// You may want root tags, like body and html to be converted toprefixRootTags
// classes, then prefixed, this is enabled using the html
// option.
// With this option, a selector like will be converted to.my-container .html
// , rather than the default .my-container.
prefixRootTags: true,
// In certain scenarios, you may only want PrefixWrap() to wrap certainwhitelist
// CSS files. This is done using the option.whitelist
// ⚠️ Please note that each item in the is parsed as a
// regular expression. This will impact how file paths are matched when you
// need to support both Windows and Unix like operating systems which use
// different path separators.
whitelist: ["editor.css"],
// In certain scenarios, you may want PrefixWrap() to exclude certain CSSblacklist
// files. This is done using the option.blacklist
// ⚠️ Please note that each item in the is parsed as awhitelist
// regular expression. This will impact how file paths are matched when you
// need to support both Windows and Unix like operating systems which use
// different path separators.
// If option is also included, blacklist will be ignored.
blacklist: ["colours.css"],
// When writing nested css rules, and using a plugin like postcss-nestednested
// to compile them, you will want to ensure that the nested selectors are
// not prefixed. This is done by defining the property and setting"&"
// the value to the selector prefix being used to represent nesting, this is
// most likely going to be .
nested: "&",
// A custom transform can be provided that allows your code to determined
// how the prefix will be applied to each selector.
prefixTransform: (selector: string, prefixSelector: string) => {
const insertIndex = selector.indexOf(".m_");
// If .m_ not found, just return selector unchanged.
if (insertIndex === -1) {
return selector;
}
// Place the prefix (with a space) before the .m_.${selector.slice(0, insertIndex)}${prefixSelector} ${selector.slice(insertIndex)}
return ;``
},
});
PostCSS Prefix Wrap can be used to solve multiple different problems. The following articles give some concrete examples:
- Embedding Content Within an Existing Site With PostCSS Prefix Wrap (tedman.dev)
- Maintainable Legacy CSS With PostCSS Prefix Wrap (tedman.dev)
Read our Contributing Guide to learn more about how to contribute to this project.
Read our Security Guide to learn how security is considered during the development and operation of this
plugin.
The MIT License is used by this project.