lit-html 2.0 Pre-release

Efficient, Expressive, Extensible HTML templates in JavaScript

🚨 About this pre-release

This is a major version pre-release of lit-html 2.0. See issue #1182 for the full list of changes planned/considered for this release.

This pre-release is not yet feature complete or API stable. Please note the breaking changes, known issues, and limitations below, and use at your risk until the stable release is available. Issues are welcome for unexpected changes not noted below or in the changelog.

🚨 Breaking changes

While lit-html 2.0 is intended to be a backward-compatible change for the majority of 1.x users, please be aware of the following notable breaking changes:

• New directive and Part API (see below for migration info)
• render() no longer clears its container on first render
• Custom templateFactory, TemplateProcessor, and custom tag functions are no longer supported

See the full changelog for more details on these and other minor breaking changes.

🚨 Known issues/limitations

• Browser support: This pre-release should run on modern browsers, however a change to factor legacy browser support (IE11, etc.) into an opt-in package is ongoing. As such, this release will not run on some older browsers. This is a temporary state.
• Limited directive implementation: The following directives are not yet implemented. This is a temporary state:
  • asyncAppend
  • asyncReplace
  • until

🚨 Migrating directives

While the API for using directives should be 100% backward-compatible with 1.x, there is a breaking change to how custom directives are authored. The API change improves ergonomics around making stateful directives while providing a clear pattern for SSR-compatible directives: only render will be called on the server, while update will not be.

⚠️ WARNING: The directive and part API changes are in progress and subject to change in future pre-releases.

import {directive, NodePart, html} from 'lit-html';

// State stored in WeakMap
const previousState = new WeakMap();

// Functional-based directive API
export const renderCounter = directive((initialValue) => (part) => {
  // When necessary, validate part type each render using `instanceof`
  if (!(part instanceof NodePart)) {
    throw new Error('renderCounter only supports NodePart');
  }
  // Retrieve value from previous state
  let value = previousState.get(part);
  // Update state
  if (previous === undefined) {
    value = initialValue;
  } else {
    value++;
  }
  // Store state
  previousState.set(part, value);
  // Update part with new rendering
  part.setValue(html`<p>${value}</p>`);
});

import {directive, Directive, NODE_PART, html} from 'lit-html';

// Class-based directive API
export const renderCounter = directive(class extends Directive {
  // State stored in class field
  value = undefined;
  constructor(part) {
    super();
    // When necessary, validate part in constructor using `part.type`
    if (part.type !== NODE_PART) {
      throw new Error('renderCounter only supports NodePart');
    }
  }
  // Any imperative updates to DOM/parts would go here
  update(part, [initialValue]) {
    // ...
  }
  // Do SSR-compatible rendering (arguments are passed from call site)
  render(initialValue) {
    // Previous state available on class field
    if (this.value === undefined) {
      this.value = initialValue;
    } else {
      this.value++;
    }
    return html`<p>${this.value}</p>`;
  }
});

lit-html

Overview

lit-html lets you write HTML templates in JavaScript with template literals.

lit-html templates are plain JavaScript and combine the familiarity of writing HTML with the power of JavaScript. lit-html takes care of efficiently rendering templates to DOM, including efficiently updating the DOM with new values.

import {html, render} from 'lit-html';

// This is a lit-html template function. It returns a lit-html template.
const helloTemplate = (name) => html`<div>Hello ${name}!</div>`;

// This renders <div>Hello Steve!</div> to the document body
render(helloTemplate('Steve'), document.body);

// This updates to <div>Hello Kevin!</div>, but only updates the ${name} part
render(helloTemplate('Kevin'), document.body);

lit-html provides two main exports:

• html: A JavaScript template tag used to produce a TemplateResult, which is a container for a template, and the values that should populate the template.
• render(): A function that renders a TemplateResult to a DOM container, such as an element or shadow root.

Installation

$ npm install lit-html

Contributing

Please see CONTRIBUTING.md.