lit-html

HTML template literals in JavaScript

lit-html lets you describe HTML templates with JavaScript template literals, and efficiently render and re-render those templates to DOM.

Example

const sayHello = (name) => html`<div>Hello ${name}!</div>`;

const container = document.querySelector('#container');
render(sayHello('Steve'), container);
// renders <div>Hello Steve!</div> to container

render(sayHello('Kevin'), container);
// updates to <div>Hello Kevin!</div>, but only updates the ${name} part

Why

lit-html has four main goals:

1. Efficient updates of previously rendered DOM.
2. Easy access the JavaScript state that needs to be injected into DOM.
3. Standard syntax without required build steps, understandable by standards-compliant tools.
4. Very small size.

Goal 1 motivate lit-html's method of creating HTML <template>s with markers for dynamic sections, rather than the final DOM tree.

For real-world template use-cases, updating existing DOM is just as important as creating the initial DOM. Using JavaScript template literals without a helper like lit-html makes it easy to create the initial DOM, but offers no help in efficiently updating it. Developer must either manually find dynamic nodes and update them, or re-render the entire tree by setting innerHTML.

Even previous HTML-in-JS proposals like E4X were only concerned with creating a static DOM tree with expression values already interpolated into the contents. That's again, good for initial rendering and not so good for updates.

lit-html is able to preserve the static vs dynamic content distinction that JavaScript template literal syntax makes clear, so it can only update the dynamic parts of a template, completely skipping the static parts on re-renders.

This should offer a performance advantage even against VDOM approaches, as most VDOM libraries do not make a distinction between static and dynamic context. The VDOM trees represent the final desired state and then the whole tree is reconciled against a previous state.

Goal 2 drives lit-html to HTML-in-JS rather than expressions-in-HTML. Any JavaScript expression can be used in a template, from any scope available where the template is defined.

Goal 3 makes tempalte literals an obvious choice over non-standard syntax like JSX.

Goal 4 is partially acheived by leveraging the built in JavaScript and HTML parsers and not doing anything that would impede using them.

Status

lit-html is very new, under initial development, and not production-ready.

• It uses JavaScript modules, and there's no build set up yet, so out-of-the-box it only runs in Safari 10.1 and Chrome Canary (with the Experimental Web Platform features flag on).
• It has a growing test suite, but it has only been run manually on Chrome Canary, Safari 10.1 and Firefox 54 with modules enabled.
• Much more test coverage is needed for complex templates, especially template composition and Function and Iterable values.
• It has not been benchmarked thouroughly yet.
• The API is likely to change.

Even without a build configuration, lit-html minified with babili and gzipped measures in at less than 1.5k. We will strive to keep the size extremely small.

How it Works

html does not return DOM nodes, unlike many other HTML with tagged template literal examples, but returns a TemplateResult - an object that contains a template and the values from expressions in the template - which can then be used to create or update DOM.

The template is created only the first time html is called on a particular template literal. On every subsequent call of html on the same template literal the exact same template is returned, only the values change.

To call html multiple times on the same template literal, it'll usually be placed in a function:

let count = 1;
const countTemplate = () => html`count: ${count++}`;

The template object is based on an actual HTML <template> element and created by setting it's innerHTML, utilizing the browser's HTML parser. The HTML is not created by concatenating the string literals expression values, but by joining the literal parts with special markers. The template object finds and remembers the locations of the markers (called "parts"). This makes the system safer from XSS attacks: a value bound to an attribute can't close the attribute, text content is automatically escaped, etc.

When a template is rendered it is cloned along with the part metadata. Values are set via setAttribute() and textContent. Some state is stored on the container to indicate that a template was already rendered there. Subsequent renders use that state to update only the dynamic parts, not the entire template instance.

Rough Algorithm Outline

html:

1. html is invoked with strings and values.

   strings are the string literal parts as a TemplateStringsArray. The same instance is returned for every evaluation of a particular template literal.

2. Look up a cached template keyed by strings, otherwise...

3. Create a new template:

   1. Join strings with a special marker, {{}}. This creates a template string that looks like a Polymer template with empty expressions.

   2. Create a new <template> element and set its innerHTML to the generated template string.

   3. Crawl the <template> contents, looking for markers and remember their location by index in Part objects. Text-content expressions create new empty text nodes which are used as placeholders.

4. Return a TemplateResult with the template and the values.

render(result, container):

1. Look for an existing TemplateInstance on container

2. If an instance exists, check that it's from the same Template as this TemplateResult

3. If the instance is not from the same Template, remove its content from container.

4. If an instance doesn't exist for the node, create one from the Template:

   1. Clone the Template's <template> contents.

   2. Iterate through the cloned nodes and create new "instance parts" for nodes that have Parts. An "instance part" is just a {part, node} record.

5. Update. For every Part:

   1. If it's an AttributePart, build up an attibute value then set the attribute.

   2. If it's a NodePart, get the value (trampoline thunks, render nested templates, etc), then either append a document fragment or set the textContent.

6. If this is the first render, append the result DOM to container.

Use in Components

HTML templates could easily be the basis for component rendering, similar to JSX in React. A component base class can call an instance method that returns a TemplateResult and then apply it to the shadow root:

class MyElement extends CoolBaseElement {

  static get observedProperties() {
    return ['message', 'name'];
  }

  title = `About lit-html`;
  body = `It's got potential.`;

  render() { return html`
    <h1>${this.title}</h1>
    <p>${this.body}</p>
  `;}
}

Benefits over HTML templates

lit-html has basically all of the benefits of HTML-in-JS systems like JSX, like:

Lighter weight

There's no need to load an expression parser and evaluator.

Seamless access to data

Since template literals are evaluated in JavaScript, their expressions have access to every variable in that scope, including globals, module and block scopes, and this inside methods.

If the main use of templates is to inject values into HTML, this breaks down a major barrier between templates and values.

Faster expression evaluation

They're just JavaScript expressions.

IDE support by default

In a type-checking environment like TypeScript, expressions are checked because they are just regular script. Hover-over docs and code-completion just work as well.

Case-sensitive parsing

Template literals preserve case, even though the HTML parser doesn't for attribute names. lit-html extracts the raw attribute names, which is useful for template syntaxes that use attribute syntax to set properties on elements.

Benefits over JSX

Native syntax

No tooling required. Understood by all JS editors and tools.

No VDOM overhead

lit-html only re-renders the dynamic parts of a template, so it doesn't produce a VDOM tree of the entire template contents, it just produces new values for each expression. By completely skipping static template parts, it saves work.

Scoped

JSX requires that the compiler be configured with the function to compile tags to. You can't mix two different JSX configurations in the same file.

The html template tag is just a variable, probably an imported function. You can have any number of similar functions in the same JS scope, or set html to different implementations.

Templates are values

JSX translates to function calls, and can't be manipulated on a per-template basis at runtime. lit-html produces a template object at runtime, which can be further processed by libraries like ShadyCSS.

CSS-compatible syntax

Because template literals use ${} as the expression delimiter, CSS's use of {} isn't interpreted as an expression. You can include style tags in your templates as you would expect:

html`
  <style>
    :host {
      background: burlywood;
    }
  </style>
`

Features

Simple expressions and literals

Anything coercible to strings are supported:

const render = () => html`foo is ${foo}`;

Attribute-value Expressions

const render = () => html`<div class="${blue}"></div>`;

Safety

Because lit-html templates are parsed before values are set, they are safer than generating HTML via string-concatenation. Attributes are set via setAttribute() and node text via textContent, so the structure of template instances cannot be accidentally changed by expression values, and values are automatically escaped.

Case-sensitive Attribute Names

Attribute parts store both the HTML-parsed name and the raw name pulled from the string literal. This allows extensions, such as those that might set properties on elements using attribute syntax, to get case-sensitive names.

const render = () => html`<div someProp="${blue}"></div>`;
render().template.parts[0].rawName === 'someProp';

Functions/Thunks

A function value is called with no arguments, in a try/catch block to be safe from exceptions:

let data;
const render = () => html`foo = ${_=>data.foo}`;

Here, data.foo throws because data is undefined, but the rest of the template renders.

Arrays/Iterables

const items = [1, 2, 3];
const render = () => html`items = ${items.map((i) => `item: ${i})}`;

const items = {
  a: 1,
  b: 23,
  c: 456,
};
const render = () => html`items = ${Object.entries(items)}`;

Nested Templates

const header = html`<h1>${title}</h1>`;
const render = () => html`
  ${header}
  <p>And the body</p>
`;

These features compose so you can include iterables of thunks that return arrays of nested templates, etc...

Extensibility

lit-html is designed to be extended by more opinionated flavors of template syntaxes. For instance, lit-html doesn't support declarative event handlers or property setting out-of-the-box. A layer on top can add that while exposing the same API, by wrapping the html tag in a new tag and modifying the result.

This is accomplished by allowing the TemplateParts of a template, which are responsible for setting new values into the DOM, to be replaced with new implementations.

Some examples of possible extensions:

• Property setting: Attribute expressions in templates could set properties on node.
• Event handlers: Specially named attributes can install event handlers.
• HTML values: lit-html creates Text nodes by default. Extensions could allow setting innerHTML.

Small Size

lit-html is less than 1.5k minified and gzipped.

API

Function html

html(callSite: TemplateStringsArray, ...expressions: any[]): TemplateResult

html is a template tag for template literals, which parses the literal as HTML and returns a TemplateResult.

Class TemplateResult

TemplateResult is a class that holds a Template object parsed from a template literal and the values from its expressions.

• Property template: Template

  A reference to the parsed Template object.

• Property values: any[]

The values returned by the template literal's expressions.

Function render(result: TemplateResult, container: Element): void

Renders a TemplateResult's template to an element using the result's values. For re-renders, only the dynamic parts are updated.

Class Template

• Property element: HTMLTemplateElement

• Property parts: Part[]

Abstract Class Part

A Part is a dynamic section of a TemplateInstance. It's value can be set to update the section.

Specially support value types are Node, Function, and TemplateResult.

• Method setValue(value: any): void

Future Work

Stateful Values

In order to support stateful repeat/if like dom-repeat and dom-if a value should be able to control it's rendering somewhat. TBD.

Async Support

Promises and Async Iterables should be supported natively.

Higher-Order Templates examples

when(cond, then, else)

An if-directive that retains the then and else instances for fast switching between the two states, like <dom-if>.

Example:

const render = () => html`
  ${when(state === 'loading',
    html`<div>Loading...</div>`,
    html`<p>${message}</p>`)}
`;

repeat(items, keyfn, template)

A loop that supports efficient re-ordering by using item keys.

Example:

const render = () => html`
  <ul>
    ${repeat(items, (i) => i.id, (i, index) => html`
      <li>${index}: ${i.name}</li>`)}
  </ul>
`;

Note, initial version is in lib/labs/repeat.ts: https://github.com/PolymerLabs/lit-html/blob/master/src/labs/repeat.ts

guard(guardExpr, template)

Only re-renders an instance if the guard expression has changed since the last render.

Since all expressions in a template literal are evaluated when the literal is evaluated, you may want to only evaluate some expensive expressions when certain other values (probably it's dependencies change). Guard would memoize function and only call it if the guard expression changed.

Example:

const render = () => html`
  <div>Current User: ${guard(user, () => user.getProfile())}</div>
`;