Skip to content
Accurate HTML parser and encoder for node.js
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


html-pe is for those who expect accuracy from their HTML parser, but are unwilling to compromise on performance. This parser handles a variety of edge cases as prescribed by the HTML5 standard and remains performant thanks to optimizations such as avoiding regular expressions.

Chunked parsing is supported, and an efficient HTML entity encoder/decoder is included.


npm install html-pe


var html = require('html-pe');

var parser = new html.Parser();

// parse chunks
parser.write('<p style="color:red">foo');

// parse entire string
parser.parse('<div id="main">bar</div>');

Optionally, an options object may be passed to the constructor (default values shown):

var parser = new html.Parser({
    trim: false,    // trim whitespace in text nodes
    decode: true    // decode HTML character entities in attribute values and text nodes

Event Handling

The parser is an EventEmitter and emits the following events:

// opening tag
parser.on('open', function (name, attributes, empty) {
    // <string> name
    // <object> attributes
    // <bool> empty: is this an empty (self-closing) tag

// text node
parser.on('text', function (text) {
    // <string> text

// closing tag
parser.on('close', function (name) {
    // <string> name

// end
parser.on('end', function () {});

Two handlers are provided:

var dom = new html.DOM(function (document) {
   // <object> document
// ...

var printer = new html.Printer();

The Printer handler pretty-prints the parsed HTML to the console. The DOM handler passes a document object to its callback, which is detailed below. Follow the structure in handlers.js to create new handlers.

DOM Manipulation

The DOM handler will parse <div id="main">hello <b>world</b></div> into the following document:

    type: 'element',
    parent: {},
    name: '',
    attributes: {},
    children: [{
        type: 'element',
        parent : [Circular],
        name: 'div',
        attributes: {
            id: 'main'
        children: [{
            type: 'text',
            parent: [Circular],
            text: 'hello '
            type: 'element',
            parent: [Circular],
            name: 'b',
            attributes: {},
            children: [{
                type: 'text',
                parent: [Circular],
                text: 'world'

Nodes are either Element nodes or Text nodes. All nodes have a textContent property. Element nodes provide the DOM navigation methods getElementById, getElementsByName, getElementsByClassName, and getElementsByTagName. Two primitive methods are also available: getElementsBy(test) and getElementBy(test) where test is a function of type Element -> bool. For example, this is how getElementsBy is used to implement getElementsByTagName:

var Element = html.Element;

Element.prototype.getElementsByTagName = function (name) {
    return this.getElementsBy(function (elem) {
        return == name;

See dom.js for details.

HTML Character Entity Encoder/Decoder

var html = require('html-pe');

html.encode('<p id="main">Hello &amp; world!</p>',
            false   // encode &<>"' only (default)
// '&lt;p id=&quot;main&quot;&gt;Hello &amp;amp; world!&lt;/p&gt;'
            true    // also encode all non-ASCII and non-printable characters
// '&lt;p&gt;&#1079;&#1076;&#1088;&#1072;&#1074;&#1089;&#1090;&#1074;&#1091;&#1081;&#1090;&#1077;!&lt;/p&gt;'

html.decode('It&apos;s &not me');
// 'It\'s ¬ me'

See encoder.js for details.


html-pe has slightly worse performance than htmlparser2. A benchmark is available in tests/bench.js.



Something went wrong with that request. Please try again.