# posthtml-match-helper

> A helper to expand CSS selectors into PostHTML matcher objects

Latest version **2.0.3** (published 2024-12-16) · MIT license · 0 weekly downloads

## Install

```sh
npm install posthtml-match-helper
pnpm add posthtml-match-helper
yarn add posthtml-match-helper
bun add posthtml-match-helper
```

## Health

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

Positive: has types; esm support; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 2.0.3 |
| Published | 2024-12-16 |
| First published | 2015-10-12 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=18 |
| Dependencies | 0 |
| Unpacked size | 8.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 11 |
| Author | Rasmus Fløe |
| Maintainers | cossssmin, phloe |
| Keywords | posthtml, posthtml-helper, posthtml-matcher |

## Links

- npm: https://www.npmjs.com/package/posthtml-match-helper
- Repository: https://github.com/posthtml/posthtml-match-helper
- Homepage: https://github.com/posthtml/posthtml-match-helper#readme
- Issues: https://github.com/posthtml/posthtml-match-helper/issues
- npm.io page: https://npm.io/package/posthtml-match-helper

## Alternatives

- [@tsparticles/shape-image](https://npm.io/package/@tsparticles/shape-image.md) — 303.7K weekly downloads
- [@tsparticles/shape-line](https://npm.io/package/@tsparticles/shape-line.md) — 233.7K weekly downloads
- [stringify-attributes](https://npm.io/package/stringify-attributes.md) — 58.6K weekly downloads
- [mobile-drag-drop](https://npm.io/package/mobile-drag-drop.md) — 46.3K weekly downloads
- [@comunica/actor-rdf-parse-html](https://npm.io/package/@comunica/actor-rdf-parse-html.md) — 29.2K weekly downloads

## Recent versions

- 2.0.3 (latest) — 2024-12-16
- 1.0.4-dev.0 (dev) — 2024-01-04
- 2.0.2 — 2024-07-03
- 2.0.1 — 2024-06-19
- 2.0.0 — 2024-02-28
- 1.0.4 — 2024-01-08
- 1.0.3 — 2022-05-03
- 1.0.2 — 2022-04-28
- 1.0.1 — 2015-10-17
- 1.0.0 — 2015-10-12

## README

<div align="center">
  <img width="150" height="150" title="PostHTML" src="https://posthtml.github.io/posthtml/logo.svg">
  <h1>posthtml-match-helper</h1>
  
  Expand CSS selectors into PostHTML matcher objects

  [![Version][npm-version-shield]][npm]
  [![Build][github-ci-shield]][github-ci]
  [![License][license-shield]][license]
  [![Downloads][npm-stats-shield]][npm-stats]
</div>

## Introduction

This PostHTML plugin can turn simple CSS selectors into [matcher objects](https://github.com/posthtml/posthtml/blob/master/README.md#match).

Supported features:

* Tags: `"div"` returns `{tag: "div"}`.
* Ids: `"#bar"` returns `{attrs: {id: "bar"}}`.
* Classes: `.foo` returns `{attrs: { class: /(?:^|\s)foo(?:\\s|$)/ }}`. Any number of classnames supported.
* Attribute selectors: any number of standard [attribute selectors](https://developer.mozilla.org/en/docs/Web/CSS/Attribute_selectors) can be used<sup><a href="#attribute_selectors_footnote">1</a></sup> including the following non-standard:
   * `[attr!=value]`: matches attributes with values that do not contain `value`.
* Multiple node selectors: `"div, span"` returns `[{tag: "div"}, {tag: "span"}]`.

**<sup><a name="attribute_selectors_footnote">1</a></sup>** Multiple attribute selectors for the same attribute are not supported (this includes mixing classnames and attribute selectors matching `class`).

The basic template for selectors (and order of features) looks like this:

```js
"tag#id.class.name[attr*=value][otherattr^='start']"
```

## Basic usage

```js
import matchHelper from "posthtml-match-helper";

tree.match(matchHelper("div.class"), function (node) {
  // do stuff with matched node...
});
```

## Advanced usage

```js
import matchHelper from "posthtml-match-helper";

tree.match(matchHelper("input.my-control[type!='radio'][checked], input[value^='foo'][checked]"), function (node) {
  // do stuff with node that matched either of the selectors...
});
```

## Classnames with escaped characters

If you need to match nodes with classnames that use escaped characters, like those in Tailwind CSS utilities with arbitrary values, use the following syntax:

```js
import matchHelper from "posthtml-match-helper";

tree.match(matchHelper("input.\\[display:none\\]"), function (node) {
  // do stuff with node that matched either of the selectors...
});
```


## The helper function

#### Arguments

* `matcher` (string) - A CSS selector that describes the node you want to match in PostHTML.

#### Returns

A matcher object or an array of matcher objects.

[npm]: https://www.npmjs.com/package/posthtml-match-helper
[npm-version-shield]: https://img.shields.io/npm/v/posthtml-match-helper.svg
[npm-stats]: http://npm-stat.com/charts.html?package=posthtml-match-helper
[npm-stats-shield]: https://img.shields.io/npm/dt/posthtml-match-helper.svg
[github-ci]: https://github.com/posthtml/posthtml-match-helper/actions/workflows/nodejs.yml
[github-ci-shield]: https://github.com/posthtml/posthtml-match-helper/actions/workflows/nodejs.yml/badge.svg
[license]: ./LICENSE
[license-shield]: https://img.shields.io/npm/l/posthtml-match-helper.svg

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