# postcss-custom-selectors

> Use Custom Selectors in CSS

Latest version **9.0.1** (published 2026-02-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install postcss-custom-selectors
pnpm add postcss-custom-selectors
yarn add postcss-custom-selectors
bun add postcss-custom-selectors
```

## Health

**Score 50/100 (C)** — status: stable.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 9.0.1 |
| Published | 2026-02-21 |
| First published | 2014-12-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Node | >=20.19.0 |
| Dependencies | 4 |
| Unpacked size | 9.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | jonathantneal, alaguna, romainmenke, yisi, moox, semigradsky |
| Keywords | at-rule, atrule, css, csswg, custom, declarative, extensions, postcss, postcss-plugin, rule, selectors, specification, w3c |

## Links

- npm: https://www.npmjs.com/package/postcss-custom-selectors
- Repository: https://github.com/csstools/postcss-plugins
- Homepage: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-custom-selectors#readme
- Issues: https://github.com/csstools/postcss-plugins/issues
- Funding: https://github.com/sponsors/csstools
- npm.io page: https://npm.io/package/postcss-custom-selectors

## Dependencies (4)

- [@csstools/css-tokenizer](https://npm.io/package/@csstools/css-tokenizer.md) ^4.0.0
- [postcss-selector-parser](https://npm.io/package/postcss-selector-parser.md) ^7.1.1
- [@csstools/css-parser-algorithms](https://npm.io/package/@csstools/css-parser-algorithms.md) ^4.0.0
- [@csstools/cascade-layer-name-parser](https://npm.io/package/@csstools/cascade-layer-name-parser.md) ^3.0.0

## Alternatives

- [style-dictionary](https://npm.io/package/style-dictionary.md) — 2.0M weekly downloads
- [postcss-merge-idents](https://npm.io/package/postcss-merge-idents.md) — 1.7M weekly downloads
- [@fontsource/noto-sans](https://npm.io/package/@fontsource/noto-sans.md) — 93.0K weekly downloads
- [uglifycss](https://npm.io/package/uglifycss.md) — 71.6K weekly downloads
- [mat4-interpolate](https://npm.io/package/mat4-interpolate.md) — 23.3K weekly downloads

## Recent versions

- 9.0.1 (latest) — 2026-02-21
- 9.0.0 — 2026-01-14
- 8.0.5 — 2025-05-27
- 8.0.4 — 2024-11-01
- 8.0.3 — 2024-10-23
- 8.0.2 — 2024-10-10
- 8.0.1 — 2024-08-18
- 8.0.0 — 2024-08-03
- 7.1.12 — 2024-07-06
- 7.1.11 — 2024-06-29
- 7.1.10 — 2024-05-04
- 7.1.9 — 2024-05-04
- 7.1.8 — 2024-03-13
- 7.1.7 — 2024-02-19
- 7.1.6 — 2023-10-09
- … 27 more at https://npm.io/package/postcss-custom-selectors/versions

## README

# PostCSS Custom Selectors [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install postcss-custom-selectors --save-dev`

[PostCSS Custom Selectors] lets you define `@custom-selector` in CSS following the [Custom Selectors Specification].

```css
@custom-selector :--heading h1, h2, h3;

article :--heading + p {
	margin-top: 0;
}

/* becomes */

article :is(h1, h2, h3) + p {
	margin-top: 0;
}
```

## Usage

Add [PostCSS Custom Selectors] to your project:

```bash
npm install postcss postcss-custom-selectors --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssCustomSelectors = require('postcss-custom-selectors');

postcss([
	postcssCustomSelectors(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is not preserved.

```js
postcssCustomSelectors({ preserve: true })
```

```css
@custom-selector :--heading h1, h2, h3;

article :--heading + p {
	margin-top: 0;
}

/* becomes */

@custom-selector :--heading h1, h2, h3;

article :is(h1, h2, h3) + p {
	margin-top: 0;
}

article :--heading + p {
	margin-top: 0;
}
```

## Modular CSS Processing

If you're using Modular CSS such as, CSS Modules, `postcss-loader` or `vanilla-extract` to name a few, you'll probably
notice that custom selectors are not being resolved. This happens because each file is processed separately so
unless you import the custom selector definitions in each file, they won't be resolved.

To overcome this, we recommend using the [PostCSS Global Data](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-global-data#readme)
plugin which allows you to pass a list of files that will be globally available. The plugin won't inject any extra code
in the output but will provide the context needed to resolve custom selectors.

For it to run it needs to be placed before the [PostCSS Custom Selectors] plugin.

```js
const postcss = require('postcss');
const postcssCustomSelectors = require('postcss-custom-selectors');
const postcssGlobalData = require('@csstools/postcss-global-data');

postcss([
	postcssGlobalData({
		files: [
			'path/to/your/custom-selectors.css'
		]
	}),
	postcssCustomSelectors(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#custom-selectors
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/postcss-custom-selectors

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Custom Selectors]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-custom-selectors
[Custom Selectors Specification]: https://drafts.csswg.org/css-extensions/#custom-selectors

---
_Source: https://npm.io/package/postcss-custom-selectors · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._