Lit

A simple library for building fast, lightweight web components

Web ComponentsUI Framework
lit/litlit.devlit-html

README

lit-html

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

Documentation


Full documentation is available at lit-html.polymer-project.org.

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

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.

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

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

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

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

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.

Installation


  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.

Contributing


Please see CONTRIBUTING.md.