A simple library for building fast, lightweight web components



Efficient, Expressive, Extensible HTML templates in JavaScript
Build Status Published on npm Join our Slack Mentioned in Awesome Lit


Full documentation is available at

Docs source is in the docs folder. To build the site yourself, see the instructions in docs/


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.

  1. ``` js
  2. import {html, render} from 'lit-html';

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

  5. // This renders
    Hello Steve!
    to the document body
  6. render(helloTemplate('Steve'), document.body);

  7. // This updates to
    Hello Kevin!
    , but only updates the ${name} part
  8. render(helloTemplate('Kevin'), document.body);
  9. ```

lit-html provides two main exports:

html: A JavaScript template tag used to produce aTemplateResult, 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.


  1. ``` sh
  2. $ npm install lit-html
  3. ```

Forward compatibility with lit-html 2.0

lit-html 2.0 has a new directive authoring API that has been back-ported to lit-html 1.4 in order to ease upgrading.

The lit-html 2.0 directive API is available in new modules whose paths are the same in lit-html 1.4 and 2.0, allowing code to import and use the APIs against either version.

You can import the new APIs like so:

  1. ```ts
  2. import {html} from 'lit-html';
  3. import {directive, Directive, Part, PartInfo, PartType} from 'lit-html/directive.js';
  4. ```

Then implement a directive class and convert it to a directive function:

  1. ```ts
  2. class MyDirective extends Directive {
  3.   // ...
  4. }
  5. /** My directive docs **/
  6. export const myDirective = directive(MyDirective);
  7. ```

Important note: The AsyncDirective base class is available, but lit-html 1.4 does _not_ implement the disconnected and reconnected callbacks.

For more details on upgrading see the Update custom directive implementations guide.


Please see