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
• The polyfill-support.js file must be loaded when using the webcomponents polyfills

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

🚨 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.

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 {html} from 'lit-html';
import {directive, Directive, PartType} from 'lit-html/directive.js';

// Class-based directive API
export const renderCounter = directive(
  class extends Directive {
    // State stored in class field
    value = undefined;
    constructor(partInfo: PartInfo, index?: number) {
      super(partInfo, index);
      // When necessary, validate part in constructor using `part.type`
      if (partInfo.type !== PartType.CHILD) {
        throw new Error('renderCounter only supports child expressions');
      }
    }
    // 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

Development mode

lit-html includes a development mode which adds additional checks that are reported in the console.

To enable development mode, add the development exports condition to your node resolve configuration.

@web/dev-server

{
  nodeResolve: {
    exportConditions: ['development'],
  }
}

Rollup

{
  plugins: [
    nodeResolve({
      exportConditions: ['development'],
    }),
  ],
}

Webpack

NOTE: Requires Webpack v5

{
  resolve: {
    conditionNames: ['development'],
  }
}

Contributing

Please see CONTRIBUTING.md.