CSSTree logo

CSSTree

CSSTree is a tool set for CSS: fast detailed parser (CSS → AST), walker (AST traversal), generator (AST → CSS) and lexer (validation and matching) based on specs and browser implementations. The main goal is to be efficient and W3C spec compliant, with focus on CSS analyzing and source-to-source transforming tasks.

Features

Detailed parsing with an adjustable level of detail

By default CSSTree parses CSS as detailed as possible, i.e. each single logical part is representing with its own AST node (see AST format for all possible node types). The parsing detail level can be changed through parser options, for example, you can disable parsing of selectors or declaration values for component parts.
Tolerant to errors by design

Parser behaves as spec says: "When errors occur in CSS, the parser attempts to recover gracefully, throwing away only the minimum amount of content before returning to parsing as normal". The only thing the parser departs from the specification is that it doesn't throw away bad content, but wraps it in a special node type (Raw) that allows processing it later.
Fast and efficient

CSSTree is created with focus on performance and effective memory consumption. Therefore it's one of the fastest CSS parsers at the moment.
Syntax validation

The build-in lexer can test CSS against syntaxes defined by W3C. CSSTree uses mdn/data as a basis for lexer's dictionaries and extends it with vendor specific and legacy syntaxes. Lexer can only check the declaration values currently, but this feature will be extended to other parts of the CSS in the future.

Projects using CSSTree

Svelte – Cybernetically enhanced web apps
SVGO – Node.js tool for optimizing SVG files
CSSO – CSS minifier with structural optimizations
NativeScript – NativeScript empowers you to access native APIs from JavaScript directly
react-native-svg – SVG library for React Native, React Native Web, and plain React web projects
penthouse – Critical Path CSS Generator
Bit – Bit is the platform for collaborating on components
and more...

Documentation

AST format
Parsing CSS → AST
- parse(source[, options])
Serialization AST → CSS
- generate(ast[, options])
AST traversal
Util functions
- Value encoding & decoding
  - property(name)
  - keyword(name)
  - ident
  - string
  - url
- AST transforming
Value Definition Syntax

Tools

AST Explorer – explore CSSTree AST format with zero setup
CSS syntax reference
CSS syntax validator

Related projects

csstree-validator – NPM package to validate CSS
stylelint-csstree-validator – plugin for stylelint to validate CSS
Grunt plugin
Gulp plugin
Sublime plugin
VS Code plugin
Atom plugin

Usage

Install with npm:

npm install css-tree

Basic usage:

import * as csstree from 'css-tree';

// parse CSS to AST
const ast = csstree.parse('.example { world: "!" }');

// traverse AST and modify it
csstree.walk(ast, (node) => {
    if (node.type === 'ClassSelector' && node.name === 'example') {
        node.name = 'hello';
    }
});

// generate CSS from AST
console.log(csstree.generate(ast));
// .hello{world:"!"}

Syntax matching:

// parse CSS to AST as a declaration value
const ast = csstree.parse('red 1px solid', { context: 'value' });

// match to syntax of `border` property
const matchResult = csstree.lexer.matchProperty('border', ast);

// check first value node is a <color>
console.log(matchResult.isType(ast.children.first, 'color'));
// true

// get a type list matched to a node
console.log(matchResult.getTrace(ast.children.first));
// [ { type: 'Property', name: 'border' },
//   { type: 'Type', name: 'color' },
//   { type: 'Type', name: 'named-color' },
//   { type: 'Keyword', name: 'red' } ]

Exports

Is it possible to import just a needed part of library like a parser or a walker. That's might useful for loading time or bundle size optimisations.

import * as tokenizer from 'css-tree/tokenizer';
import * as parser from 'css-tree/parser';
import * as walker from 'css-tree/walker';
import * as lexer from 'css-tree/lexer';
import * as definitionSyntax from 'css-tree/definition-syntax';
import * as data from 'css-tree/definition-syntax-data';
import * as dataPatch from 'css-tree/definition-syntax-data-patch';
import * as utils from 'css-tree/utils';

Using in a browser

Bundles are available for use in a browser:

dist/csstree.js – minified IIFE with csstree as global

<script src="node_modules/css-tree/dist/csstree.js"></script>
<script>
  csstree.parse('.example { color: green }');
</script>

dist/csstree.esm.js – minified ES module

<script type="module">
  import { parse } from 'node_modules/css-tree/dist/csstree.esm.js'
  parse('.example { color: green }');
</script>

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 csstree from 'https://cdn.jsdelivr.net/npm/css-tree';
  import * as csstree from 'https://unpkg.com/css-tree';
</script>

<!-- IIFE with an export to global -->
<script src="https://cdn.jsdelivr.net/npm/css-tree/dist/csstree.js"></script>
<script src="https://unpkg.com/css-tree/dist/csstree.js"></script>

Top level API

API map

License

MIT

Current Tags

2.3.1 ... latest (2 years ago)

55 Versions

2.3.1 ... 2 years ago
2.3.0 ... 2 years ago
2.2.1 ... 2 years ago
2.2.0 ... 2 years ago
2.1.0 ... 3 years ago
2.0.4 ... 3 years ago
2.0.3 ... 3 years ago
2.0.2 ... 3 years ago
2.0.1 ... 3 years ago
2.0.0 ... 3 years ago
1.1.3 ... 4 years ago
1.1.2 ... 4 years ago
1.1.1 ... 4 years ago
1.1.0 ... 4 years ago
1.0.1 ... 4 years ago
1.0.0 ... 4 years ago
1.0.0-alpha.39 ... 5 years ago
1.0.0-alpha.38 ... 5 years ago
1.0.0-alpha.37 ... 5 years ago
1.0.0-alpha.36 ... 5 years ago
1.0.0-alpha.35 ... 5 years ago
1.0.0-alpha.34 ... 5 years ago
1.0.0-alpha.33 ... 5 years ago
1.0.0-alpha.32 ... 5 years ago
1.0.0-alpha.31 ... 5 years ago
1.0.0-alpha.30 ... 5 years ago
1.0.0-alpha.29 ... 7 years ago
1.0.0-alpha.28 ... 7 years ago
1.0.0-alpha.27 ... 7 years ago
1.0.0-alpha.26 ... 7 years ago
1.0.0-alpha25 ... 7 years ago
1.0.0-alpha24 ... 7 years ago
1.0.0-alpha23 ... 7 years ago
1.0.0-alpha22 ... 7 years ago
1.0.0-alpha21 ... 7 years ago
1.0.0-alpha20 ... 7 years ago
1.0.0-alpha19 ... 8 years ago
1.0.0-alpha18 ... 8 years ago
1.0.0-alpha17 ... 8 years ago
1.0.0-alpha16 ... 8 years ago
1.0.0-alpha15 ... 8 years ago
1.0.0-alpha14 ... 8 years ago
1.0.0-alpha13 ... 8 years ago
1.0.0-alpha12 ... 8 years ago
1.0.0-alpha11 ... 8 years ago
1.0.0-alpha10 ... 8 years ago
1.0.0-alpha9 ... 8 years ago
1.0.0-alpha8 ... 8 years ago
1.0.0-alpha7 ... 8 years ago
1.0.0-alpha6 ... 8 years ago
1.0.0-alpha5 ... 8 years ago
1.0.0-alpha4 ... 8 years ago
1.0.0-alpha3 ... 8 years ago
1.0.0-alpha2 ... 8 years ago
1.0.0-alpha ... 8 years ago