@xof/html

v1.0.0

Published

12 days ago

Fast and lightweight HTML parser and DOM manipulation library for Node.js.

XOF HTML

Fast and lightweight HTML parser and DOM manipulation library for Node.js.

XOF HTML provides a simple $() API for parsing HTML, selecting elements, reading attributes, extracting text, traversing elements, and manipulating the DOM.

Installation

npm install @xof/html

For fetching HTML from websites, you can use @xof/fetch:

npm install @xof/fetch

Basic Usage

const { load } = require('@xof/html');

const html = `
<!DOCTYPE html>
<html>
<head>
    <title>Hello XOF</title>
</head>
<body>
    <h1>Hello World</h1>

    <a href="/one">One</a>
    <a href="/two">Two</a>
</body>
</html>
`;

const $ = load(html);

console.log($('title').text());
// Hello XOF

console.log($('h1').text());
// Hello World

console.log($('a').length);
// 2

console.log($('a').first().attr('href'));
// /one

Using with @xof/fetch

XOF HTML works well with @xof/fetch for fetching and parsing remote HTML.

const go = require('@xof/fetch');
const { load } = require('@xof/html');

async function main() {
    const res = await go.get('https://example.com');

    const html = await res.text();

    const $ = load(html);

    console.log($('title').text());
}

main();

You can also extract multiple elements:

const go = require('@xof/fetch');
const { load } = require('@xof/html');

async function main() {
    const res = await go.get('https://example.com');

    const html = await res.text();
    const $ = load(html);

    $('a').each((index, element) => {
        console.log(
            $(element).text(),
            $(element).attr('href')
        );
    });
}

main();

Selecting Elements

Tag

$('h1');
$('p');
$('a');
$('div');

ID

$('#app');
$('#content');

Class

$('.container');
$('.card');

Descendant

$('.container .card');
$('article h2');

Child

$('.container > .card');

Multiple Selectors

$('h1, h2, h3');

Attribute

$('a[href]');
$('input[type="text"]');

Reading Text

const title = $('h1').text();

console.log(title);

For multiple elements:

$('p').each((index, element) => {
    console.log($(element).text());
});

Reading Attributes

const href = $('a').first().attr('href');

console.log(href);

You can read any attribute:

$('img').first().attr('src');
$('div').first().attr('class');
$('input').first().attr('value');

Checking Elements

console.log($('h1').length);

Check whether an element exists:

if ($('.article').length) {
    console.log('Article found');
}

Iterating Elements

$('a').each((index, element) => {
    console.log(
        index,
        $(element).text(),
        $(element).attr('href')
    );
});

Working with an Element

Elements can be passed back into $():

$('a').each((index, element) => {
    const link = $(element);

    console.log(link.text());
    console.log(link.attr('href'));
});

Traversal

$('article').find('h2');

$('h2').parent();

$('h2').children();

$('h2').first();

$('h2').last();

$('h2').next();

$('h2').prev();

HTML

Get the HTML inside an element:

const html = $('#content').html();

console.log(html);

Get the outer HTML:

const html = $('#content').outerHTML();

console.log(html);

DOM API

The underlying document is available through $:

const $ = load(html);

const document = $.document;

console.log(
    document.querySelector('title')
);

You can also use the DOM API directly:

const element =
    $.document.querySelector('h1');

console.log(element.textContent);
console.log(element.getAttribute('class'));

Example: Simple Scraper

const go = require('@xof/fetch');
const { load } = require('@xof/html');

async function scrape(url) {
    const res = await go.get(url);

    const html = await res.text();
    const $ = load(html);

    const result = [];

    $('a').each((index, element) => {
        result.push({
            text: $(element).text(),
            href: $(element).attr('href')
        });
    });

    return result;
}

async function main() {
    const links =
        await scrape('https://example.com');

    console.log(links);
}

main();

API

`load(html, options?)`

Creates a document from an HTML string and returns the $ selector function.

const $ = load(html);

`$(selector)`

Select elements from the loaded document.

$('h1');
$('.card');
$('#app');
$('a[href]');

`$(element)`

Wrap an existing DOM element.

const element =
    $.document.querySelector('h1');

const heading = $(element);

console.log(heading.text());

`$.document`

Access the parsed document.

console.log($.document);

Requirements

Node.js 18+
CommonJS