# postcss-selector-parser

> Selector parser with built in methods for working with selector strings.

Latest version **7.1.6** (published 2026-09-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install postcss-selector-parser
pnpm add postcss-selector-parser
yarn add postcss-selector-parser
bun add postcss-selector-parser
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 7.1.6 |
| Published | 2026-09-03 |
| First published | 2015-05-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=4 |
| Dependencies | 2 |
| Unpacked size | 210 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 214 |
| Maintainers | moox, ai, chriseppstein, jonathantneal, evilebottnawi |

## Links

- npm: https://www.npmjs.com/package/postcss-selector-parser
- Repository: https://github.com/postcss/postcss-selector-parser
- Issues: https://github.com/postcss/postcss-selector-parser/issues
- npm.io page: https://npm.io/package/postcss-selector-parser

## Dependencies (2)

- [cssesc](https://npm.io/package/cssesc.md) ^3.0.0
- [util-deprecate](https://npm.io/package/util-deprecate.md) ^1.0.2

## Recent versions

- 7.1.6 (latest) — 2026-09-03
- 6.1.4 (legacy-v6) — 2026-06-11
- 7.1.5 — 2026-08-07
- 7.1.4 — 2026-06-11
- 7.1.3 — 2026-06-11
- 6.1.3 — 2026-06-11
- 7.1.2 — 2026-06-09
- 7.1.1 — 2025-11-27
- 7.1.0 — 2025-02-07
- 7.0.0 — 2024-10-23
- 6.1.2 — 2024-08-12
- 6.1.1 — 2024-07-11
- 6.1.0 — 2024-05-22
- 6.0.16 — 2024-03-13
- 6.0.15 — 2023-12-29
- … 54 more at https://npm.io/package/postcss-selector-parser/versions

## README

# postcss-selector-parser

[![npm package version](https://img.shields.io/github/package-json/v/postcss/postcss-selector-parser) ![npm downloads](https://img.shields.io/npm/dm/postcss-selector-parser)](https://www.npmjs.com/package/postcss-selector-parser)
[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/postcss/postcss-selector-parser/test.yml)](https://github.com/postcss/postcss-selector-parser/actions)
[![License](https://img.shields.io/github/license/postcss/postcss-selector-parser)](https://github.com/postcss/postcss-selector-parser)  

> Selector parser with built in methods for working with selector strings.

## Install

With [npm](https://npmjs.com/package/postcss-selector-parser) do:

```
npm install postcss-selector-parser
```

## Quick Start

```js
const parser = require('postcss-selector-parser');
const transform = selectors => {
    selectors.walk(selector => {
        // do something with the selector
        console.log(String(selector))
    });
};

const transformed = parser(transform).processSync('h1, h2, h3');
```

To normalize selector whitespace:

```js
const parser = require('postcss-selector-parser');
const normalized = parser().processSync('h1, h2, h3', {lossless: false});
// -> h1,h2,h3
```

Async support is provided through `parser.process` and will resolve a Promise
with the resulting selector string.

## API

Please see [API.md](API.md).

## Security

### Selector nesting depth (CVE-2026-9358)

The parser walks the selector AST recursively, both when parsing and when
serializing it back to a string (`.toString()`). In versions up to and
including `7.1.1`, a selector with extreme nesting — for example thousands of
nested `:not(...)` — could recurse deeply enough to overflow the call stack and
throw `RangeError: Maximum call stack size exceeded`, a potential
denial-of-service when processing untrusted CSS.

This is now bounded by a maximum nesting depth (default: `256`). Beyond that
depth, parsing and serialization throw a regular, catchable `Error` at a
predictable point instead of relying on the runtime hitting its stack limit.
The default is far above any realistic selector, so it does not affect normal
use.

**Practical impact is low.** The only attacker-controlled input is the selector
string itself, which is now capped by the default limit. The limit is
adjustable through the `maxNestingDepth` option, but that option is trusted
configuration provided by the integrating code — it is never derived from the
parsed CSS, so a malicious selector cannot change it:

```js
// Tighten the limit when parsing untrusted input:
parser().processSync(untrustedSelector, {maxNestingDepth: 128});
```

Raising `maxNestingDepth` to a very large value is an explicit, informed choice
and can reintroduce the stack-overflow risk in environments with a small call
stack (e.g. browser workers). The default is recommended unless you have a
specific need.

## Credits

* Huge thanks to Andrey Sitnik (@ai) for work on PostCSS which helped
  accelerate this module's development.

## License

MIT

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