3.0.0 • Public • Published

NPM version Build Status Coverage Status

CSSTree Validator

CSS validator built on CSSTree


> npm install csstree-validator

Validate CSS string or CSSTree's AST:

import { validate } from 'csstree-validator';
// Commonjs:
// const { validate } = require('csstree-validator');

const filename = 'demo/example.css';
const css = '.class { pading: 10px; border: 1px super red }';

console.log(validate(css, filename));
// [
//   SyntaxError [SyntaxReferenceError]: Unknown property `pading` {
//     reference: 'pading',
//     property: 'pading',
//     offset: 9,
//     line: 1,
//     column: 10
//   },
//   SyntaxError [SyntaxMatchError]: Mismatch {
//     message: 'Invalid value for `border` property',
//     rawMessage: 'Mismatch',
//     syntax: '<line-width> || <line-style> || <color>',
//     css: '1px super red',
//     mismatchOffset: 4,
//     mismatchLength: 5,
//     offset: 35,
//     line: 1,
//     column: 36,
//     loc: { source: 'demo/example.css', start: [Object], end: [Object] },
//     property: 'border',
//     details: 'Mismatch\n' +
//       '  syntax: <line-width> || <line-style> || <color>\n' +
//       '   value: 1px super red\n' +
//       '  ------------^'
//   }
// ]

Another option is to use helpers to validate a file or a directory and one of buildin reporters:

import { validateFile, reporters } from 'csstree-validator';


Validate methods

  • validate(css, filename)
  • validateAtrule(node)
  • validateAtrulePrelude(atrule, prelude, preludeLoc)
  • validateAtruleDescriptor(atrule, descriptor, value, descriptorLoc)
  • validateDeclaration(property, value, valueLoc)
  • validateRule(node)


All helper function return an object where key is a path to a file and value is an array of errors. The result object is iterable (has Symbol.iterator) and can be used with for ... of or ... operator.

const result = validateFile('path/to/file.css');

for (const [filename, errors] of result) {
  // ...
  • validateString(css, filename)
  • validateDictionary(dictionary)
  • validateFile(filename)
  • validatePath(searchPath, filter)
  • validatePathList(pathList, filter)


  • json
  • console
  • checkstyle
  • gnu

Using in a browser

Available bundles to use in a browser:

  • dist/csstree-validator.js – minified IIFE with csstreeValidator as a global
<script src="node_modules/csstree-validator/dist/csstree-validator.js"></script>
  const errors = csstreeValidator.validate('.some { css: source }');
  • dist/csstree-validator.esm.js – minified ES module
<script type="module">
  import { validate } from "csstree-validator/dist/csstree-validator.esm.js";

  const errors = validate('.some { css: source }');

One of CDN services like unpkg or jsDelivr can be used. By default (for short path) a ESM version is exposing. For IIFE version a full path to a bundle should be specified:

<!-- ESM -->
<script type="module">
  import * as csstreeValidator from 'https://cdn.jsdelivr.net/npm/csstree-validator';
  import * as csstreeValidator from 'https://unpkg.com/csstree-validator';

<!-- IIFE with csstreeValidator as a global -->
<script src="https://cdn.jsdelivr.net/npm/csstree-validator/dist/csstree-validator.js"></script>
<script src="https://unpkg.com/csstree-validator/dist/csstree-validator.js"></script>

NOTE: Helpers and reporters are not available for browser's version.

CLI (terminal command)

> npm install -g csstree-validator
> csstree-validator /path/to/style.css
> csstree-validator -h

    csstree-validate [fileOrDir] [options]


    -h, --help                     Output usage information
    -r, --reporter <nameOrFile>    Output formatter: console (default), checkstyle, json, gnu
                                   or <path to a module>
    -v, --version                  Output version

Custom reporters

In addition to predefined (buildin) reporters, you can specify the path to a module or a package with a custom reporter. Such module should export a single function which takes the validation result object and returns a string:

export default function(result) {
  const output = '';

  for (const [filename, errors] of result) {
    // ...

  return output;

// For CommonJS:
// module.exports = function(result) { ... }

The specifier for a custom reporter might be:

  • ESM module – a full path to a file with .js extension
  • CommonJS module – a full path to a file with .cjs extension
  • ESM package – a package name or a full path to package's module (i.e. package/lib/index.js)
  • CommonJS package – a package name or a path to package's module (i.e. package/lib/index.js, package/lib/index or package/lib)
  • Dual package – a package name or a full path to package's module

The resolution algorithm is testing reporter option value in the following order:

  • If a value is a path to a file (a base dir for relative paths is process.cwd()), then use it a module
  • If a value is a path to a package module (a base dir for node_modules is process.cwd()), then use package's module
  • Otherwise the value should be a name of one of predifined reporter, or an error will be raised

Ready to use

Plugins that are using csstree-validator:




npm i csstree-validator

DownloadsWeekly Downloads






Unpacked Size

369 kB

Total Files


Last publish


  • lahmatiy