apply-html

It's .innerHTML = '' for the 21st century!

Yet another library to diff and patch an existing DOM tree by efficiently comparing it to a string. Why? This library is a little bit different than others. It makes use of an HTML <template>'s unique ability to create an inert document fragment. These amazing creatures' features include:

• A real DOM tree
• Multiple root nodes
• Will not trigger resource loading prematurely
• Will not apply embedded stylesheets prematurely
• Will not trigger custom element constructors or lifecycle events prematurely

The live DOM is then patched with the inert fragment using nanomorph, a hyper-fast diffing algorithm for real DOM nodes. This ensures that things only start happening if and when they're supposed to, organically.

Play with it on CodePen.

Install

$ npm install --save apply-html

or

<script src="https://wzrd.in/standalone/apply-html"></script>

Usage

Patching

const { apply } = require('apply-html');

apply(document.body, '<h1 class="day">Hello World</h1>');

console.log(document.body.innerHTML);
// -> <h1 class="day">Hello World</h1>

apply(document.body, '<h1 class="night">Goodnight Moon</h1>');

console.log(document.body.innerHTML);
// -> <h1 class="night">Goodnight Moon</h1>

Interpolation and Escaping

const { apply, html, raw } = require('apply-html');

const foo = '<em>foo</em>';
const bar = raw('<em>bar</em>');
const baz = html`<strong>baz</strong>`;

apply(document.body, html`
    ${foo}
    ${bar}
    ${baz}
`);

console.log(document.body.innerHTML);
// -> &lt;em&gt;foo&lt;/em&gt;
// -> <em>bar</em>
// -> <strong>baz</strong>

Server-side Rendering

The html and raw functions never touch the DOM so they're completely safe to use server-side.

const http = require('http');
const { html } = require('apply-html');

const content = html`
    <h1>Hello <em>World</em></h1>
    <p>How are you today?</p>
`;

module.exports = http
    .createServer((req, res) => res.end(content.toString()))
    .listen(3000);

API

apply(element, string): Element

• element {Element} DOM element with children to be patched.
• string {String|SafeString} String or SafeString containing safe HTML to render.

Updates the content of the given element, making the fewest possible changes required to match the given string of HTML. The string is converted into an HTML <template> and the DOM trees are compared. Returns the updated element.

html`string`: SafeString

A template tag that creates a new SafeString containing a string of HTML. Interpolated values are serialized based on type:

• Array - Items are serialized then joined with an empty string ('').
• Boolean|null|undefined - Converted to an empty string ('').
• Function - Throws a TypeError.
• Object - Converted to an HTML-escaped JSON blob.
• SafeString|Number - Inserted as-is.
• String - HTML-escaped to safeguard against XSS. To opt out of escaping, use raw().

raw(string): SafeString

• string {String} String of safe HTML.

Wraps a string in a SafeString to indicate that it's safe to be inserted into the document. Only use on trusted strings to safeguard against XSS.

SafeString

new SafeString(string)

• string {any} - The value to wrap. Will be coerced into a string with String().

Wraps a string to indicate that the string is safe to be inserted into the DOM. Only use on trusted strings to safeguard against XSS.

SafeString Properties

.raw {String}

The wrapped string.

.length {Number}

Length of the wrapped string. Read only.

SafeString Methods

.toJSON(): String

Returns the raw string.

.toString(): String

Returns the raw string.

Acknowledgements

Standing on the shoulders of these giants:

• bel
• diff-dom
• hyperhtml
• lit-html
• morphdom
• petit-dom
• react
• snabbdom
• vue.js
• and more...

Contribute

Standards for this project, including tests, code coverage, and semantics are enforced with a build tool. Pull requests must include passing tests with 100% code coverage and no linting errors.

Test

$ npm test

MIT © Shannon Moeller