README.md
1# lit-html
2Efficient, Expressive, Extensible HTML templates in JavaScript
3
4[](https://travis-ci.org/Polymer/lit-html)
5[](https://www.npmjs.com/package/lit-html)
6[](https://www.polymer-project.org/slack-invite)
7[](https://github.com/web-padawan/awesome-lit-html)
8
9## Documentation
10
11Full documentation is available at [lit-html.polymer-project.org](https://lit-html.polymer-project.org).
12
13Docs source is in the `docs` folder. To build the site yourself, see the instructions in [docs/README.md](docs/README.md).
14
15## Overview
16
17`lit-html` lets you write [HTML templates](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/template) in JavaScript with [template literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals).
18
19lit-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.
20
21```javascript
22import {html, render} from 'lit-html';
23
24// This is a lit-html template function. It returns a lit-html template.
25const helloTemplate = (name) => html`<div>Hello ${name}!</div>`;
26
27// This renders <div>Hello Steve!</div> to the document body
28render(helloTemplate('Steve'), document.body);
29
30// This updates to <div>Hello Kevin!</div>, but only updates the ${name} part
31render(helloTemplate('Kevin'), document.body);
32```
33
34`lit-html` provides two main exports:
35
36 * `html`: A JavaScript [template tag](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_template_literals) used to produce a `TemplateResult`, which is a container for a template, and the values that should populate the template.
37 * `render()`: A function that renders a `TemplateResult` to a DOM container, such as an element or shadow root.
38
39## Installation
40
41```bash
42$ npm install lit-html
43```
44
45## Contributing
46
47Please see [CONTRIBUTING.md](./CONTRIBUTING.md).
48
){kind=link}
){kind=link}
){kind=link}
){kind=link}