# postcss-html

> PostCSS syntax for parsing HTML (and HTML-like)

Latest version **2.0.0** (published 2026-07-31) · MIT license · 0 weekly downloads

## Install

```sh
npm install postcss-html
pnpm add postcss-html
yarn add postcss-html
bun add postcss-html
```

## Health

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

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

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2026-07-31 |
| First published | 2017-05-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | ^22.12 \|\| >=24 |
| Dependencies | 3 |
| Unpacked size | 28.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 33 |
| Author | gucong |
| Maintainers | jeddy3, ai, gucong, ota-meshi |
| Keywords | postcss, syntax, html, vue, quickapp, PHP, css, less, sass, scss, sss, sugarss |

## Links

- npm: https://www.npmjs.com/package/postcss-html
- Repository: https://github.com/ota-meshi/postcss-html
- Homepage: https://github.com/ota-meshi/postcss-html#readme
- Issues: https://github.com/ota-meshi/postcss-html/issues
- npm.io page: https://npm.io/package/postcss-html

## Dependencies (3)

- [js-tokens](https://npm.io/package/js-tokens.md) ^9.0.0
- [htmlparser2](https://npm.io/package/htmlparser2.md) ^9.1.0
- [postcss-safe-parser](https://npm.io/package/postcss-safe-parser.md) ^7.0.1

## 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.0 (latest) — 2026-07-31
- 1.0.0-alpha.4 (next) — 2021-10-21
- 1.8.1 — 2026-01-13
- 1.8.0 — 2025-01-14
- 1.7.0 — 2024-05-08
- 1.6.0 — 2024-01-12
- 1.5.0 — 2022-07-07
- 1.4.1 — 2022-04-15
- 1.4.0 — 2022-04-15
- 1.3.1 — 2022-04-13
- 1.3.0 — 2021-11-24
- 1.2.0 — 2021-10-29
- 1.1.1 — 2021-10-26
- 1.1.0 — 2021-10-24
- 1.0.2 — 2021-10-24
- … 46 more at https://npm.io/package/postcss-html/versions

## README

# PostCSS HTML Syntax

[![NPM license](https://img.shields.io/npm/l/postcss-html.svg)](https://www.npmjs.com/package/postcss-html)
[![NPM version](https://img.shields.io/npm/v/postcss-html.svg?style=flat-square)](https://www.npmjs.com/package/postcss-html)
[![NPM downloads](https://img.shields.io/npm/dw/postcss-html.svg)](http://www.npmtrends.com/postcss-html)
[![NPM downloads](https://img.shields.io/npm/dm/postcss-html.svg)](http://www.npmtrends.com/postcss-html)
[![NPM downloads](https://img.shields.io/npm/dy/postcss-html.svg)](http://www.npmtrends.com/postcss-html)
[![Build Status](https://github.com/ota-meshi/postcss-html/workflows/CI/badge.svg?branch=master)](https://github.com/ota-meshi/postcss-html/actions?query=workflow%3ACI)

<img align="right" width="95" height="95"
 title="Philosopher’s stone, logo of PostCSS"
 src="http://postcss.github.io/postcss/logo.svg">

[PostCSS](https://github.com/postcss/postcss) syntax for parsing HTML (and HTML-like)

- [Vue Single-File Components](https://vuejs.org/guide/scaling-up/sfc.html)
- [Svelte Components](https://svelte.dev/docs#component-format)
- [Astro Components](https://docs.astro.build/en/core-concepts/astro-components/)
- [PHP](http://php.net)
- [Quick App](https://doc.quickapp.cn/framework/source-file.html)
- [XSLT](https://www.w3.org/TR/xslt-30/)

## Getting Started

First thing's first, install the module:

```bash
npm install postcss-html --save-dev
```

postcss-html is an ES module and requires Node.js `^22.12 || >=24`. CommonJS consumers on those Node.js versions can still load it with `require("postcss-html")`.

If you want support SCSS/SASS/LESS/SugarSS syntax, you need to install the corresponding module.

- SCSS: [postcss-scss](https://github.com/postcss/postcss-scss)
- SASS: [postcss-sass](https://github.com/aleshaoleg/postcss-sass)
- LESS: [postcss-less](https://github.com/shellscape/postcss-less)
- SugarSS: [sugarss](https://github.com/postcss/sugarss)
- Stylus: [postcss-styl](https://github.com/ota-meshi/postcss-styl)

## Use Cases

```js
import postcss from 'postcss';
import postcssHtml from 'postcss-html';
import postcssScss from 'postcss-scss';
import postcssLess from 'postcss-less';
import postcssSafeParser from 'postcss-safe-parser';

const syntax = postcssHtml({
    // syntax for parse scss (non-required options)
    scss: postcssScss,
    // syntax for parse less (non-required options)
    less: postcssLess,
    // syntax for parse css blocks (non-required options)
    css: postcssSafeParser,
});
postcss(plugins).process(source, { syntax: syntax }).then(function (result) {
    // An alias for the result.css property. Use it with syntaxes that generate non-CSS output.
    result.content
});
```

If you want support SCSS/SASS/LESS/SugarSS syntax, you need to install these module:

- SCSS: [postcss-scss](https://github.com/postcss/postcss-scss)
- SASS: [postcss-sass](https://github.com/aleshaoleg/postcss-sass)
- LESS: [postcss-less](https://github.com/shellscape/postcss-less)
- SugarSS: [sugarss](https://github.com/postcss/sugarss)
- Stylus: [postcss-styl](https://github.com/ota-meshi/postcss-styl)

## Advanced Use Cases

### Options

```js
import postcssHtml from 'postcss-html';
import postcssSass from 'postcss-sass';
import sugarss from 'sugarss';
import postcssCustomSyntax from 'postcss-custom-syntax';

const options = {
    rules: [
        {
            // custom language
            test: /^postcss$/i,
            lang: 'scss'
        },
        {
            // custom language
            test: /^customcss$/i,
            lang: 'custom'
        },
    ],

    // custom parser for CSS (using `postcss-safe-parser`)
    css: 'postcss-safe-parser',
    // custom parser for SASS (PostCSS-compatible syntax.)
    sass: postcssSass,
    // custom parser for SCSS (by module name)
    scss: 'postcss-scss',
    // custom parser for LESS (by module path)
    less: './node_modules/postcss-less',
    // custom parser for SugarSS
    sugarss: sugarss,
    // custom parser for custom language
    custom: postcssCustomSyntax,
}
const syntax = postcssHtml(options);
```

## Turning PostCSS off from within your HTML

PostCSS can be temporarily turned off by using special comments in your HTML. For example:

```html
<html>
<body>
<!-- postcss-ignore -->
<a style="color: red;" description="style is not parsed."></a>

<a style="color: red;" description="style is parsed."></a>
```

```html
<html>
<body>
<!-- postcss-disable -->
<a style="color: red;" description="style is not parsed."></a>
<a style="color: red;" description="style is not parsed."></a>
<!-- postcss-enable -->

<a style="color: red;" description="style is parsed."></a>
```

## Linting with Stylelint

The main use case of this plugin is to apply linting with [Stylelint] to `<style>` tags and `<div style="*">` property in HTML (and HTML-like).

You can use it by configuring your `stylelint` config as follows:

```json
{
    "overrides": [
        {
            "files": ["*.html", "**/*.html"],
            "customSyntax": "postcss-html"
        }
    ]
}
```

You can use it more easily if you use an already configured sharable config.

```diff
{
+    "extends": [
+        "stylelint-config-html",
         // If you are using Vue.
+        "stylelint-config-recommended-vue"
+    ],
-    "overrides": [
-        {
-            "files": ["*.html", "**/*.html"],
-            "customSyntax": "postcss-html"
-        }
-    ]
}
```

- [stylelint-config-html]
- [stylelint-config-recommended-vue]

[Stylelint]: https://stylelint.io/
[stylelint-config-html]: https://github.com/ota-meshi/stylelint-config-html
[stylelint-config-recommended-vue]: https://github.com/ota-meshi/stylelint-config-recommended-vue

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