1 | # lit-html 2.0
|
2 |
|
3 | Efficient, Expressive, Extensible HTML templates in JavaScript
|
4 |
|
5 | [![Build Status](https://github.com/lit/lit/workflows/Tests/badge.svg)](https://github.com/lit/lit/actions?query=workflow%3ATests)
|
6 | [![Published on npm](https://img.shields.io/npm/v/lit-html/next)](https://www.npmjs.com/package/lit-html)
|
7 | [![Join our Slack](https://img.shields.io/badge/slack-join%20chat-4a154b.svg)](https://www.polymer-project.org/slack-invite)
|
8 | [![Mentioned in Awesome Lit](https://awesome.re/mentioned-badge.svg)](https://github.com/web-padawan/awesome-lit)
|
9 |
|
10 | lit-html is the template system that powers the [Lit](https://lit.dev) library for building fast web components. When using `lit-html` to develop web components, most users should import lit-html via the [`lit`](https://www.npmjs.com/package/lit) package rather than installing and importing from `lit-html` directly.
|
11 |
|
12 | ## About this release
|
13 |
|
14 | This is a stable release of `lit-html` 2.0 (part of the Lit 2.0 release). If upgrading from previous versions of `lit-html`, please note the minor breaking changes from lit-html 1.0 in the [Upgrade Guide](https://lit.dev/docs/releases/upgrade/).
|
15 |
|
16 | ## Documentation
|
17 |
|
18 | Full documentation is available at [lit.dev](https://lit.dev).
|
19 |
|
20 | ## Overview
|
21 |
|
22 | `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).
|
23 |
|
24 | 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.
|
25 |
|
26 | ```javascript
|
27 | import {html, render} from 'lit-html';
|
28 |
|
29 | // This is a lit-html template function. It returns a lit-html template.
|
30 | const helloTemplate = (name) => html`<div>Hello ${name}!</div>`;
|
31 |
|
32 | // This renders <div>Hello Steve!</div> to the document body
|
33 | render(helloTemplate('Steve'), document.body);
|
34 |
|
35 | // This updates to <div>Hello Kevin!</div>, but only updates the ${name} part
|
36 | render(helloTemplate('Kevin'), document.body);
|
37 | ```
|
38 |
|
39 | `lit-html` provides two main exports:
|
40 |
|
41 | - `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.
|
42 | - `render()`: A function that renders a `TemplateResult` to a DOM container, such as an element or shadow root.
|
43 |
|
44 | ## Installation
|
45 |
|
46 | ```bash
|
47 | $ npm install lit-html
|
48 | ```
|
49 |
|
50 | Or use from `lit`:
|
51 |
|
52 | ```bash
|
53 | $ npm install lit
|
54 | ```
|
55 |
|
56 | ## Contributing
|
57 |
|
58 | Please see [CONTRIBUTING.md](./CONTRIBUTING.md).
|