Lightning-fast templates & Web Components: lit-html & LitElement

Today we're excited to announce the first stable releases of our two next-generation web development libraries: lit-html and LitElement.

lit-html is a tiny, fast, expressive library for HTML templating. LitElement is a simple base class for creating Web Components with lit-html templates.

If you've been following the projects, you probably know what lit-html and LitElement are all about (and you can skip to the end if you like). If you're new to lit-html and LitElement, read on for an overview.

lit-html is a tiny (just over 3k bundled, minified, and gzipped) and fast JavaScript library for HTML templating. lit-html works well with functional programming approaches, letting you express your application's UI declaratively, as a function of its state.

const myTemplate = (name) => html`
  <div>
    Hi, my name is ${name}.
  </div>
`;

It's simple to render a lit-html template:

render(myTemplate('Ada'), document.body);

Re-rendering a template only updates the data that's changed:

render(myTemplate('Grace'), document.body);

lit-html is efficient, expressive, and extensible:

• Efficient. lit-html is lightning fast. When data changes, lit-html doesn't need to do any diffing; instead, it remembers where you inserted expressions in your template and only updates these dynamic parts.

• Expressive. lit-html gives you the full power of JavaScript, declarative UI, and functional programming patterns. The expressions in a lit-html template are just JavaScript, so you don't need to learn a custom syntax and you have all the expressiveness of the language at your disposal. lit-html supports many kinds of values natively: strings, DOM nodes, arrays and more. Templates themselves are values that can be computed, passed to and from functions, and nested.

• Extensible: lit-html is also customizable and extensible—your very own template construction kit. Directives customize how values are handled, allowing for asynchronous values, efficient keyed-repeats, error boundaries, and more. lit-html includes several ready-to-use directives and makes it easy to define your own.

A number of libraries and projects have already incorporated lit-html. You can find a list of some of these libraries in the awesome-lit-html repo on GitHub.

If templating is all you need, you can get started now with the lit-html docs. If you'd like to build components to use in your app or share with your team, read on to learn more.

LitElement is a lightweight base class that makes it easier than ever to build and share Web Components.

LitElement uses lit-html to render components and adds APIs to declare reactive properties and attributes. Elements update automatically when their properties change. And they update fast, without diffing.

Here's a simple LitElement component:

@customElement('name-tag')
class NameTag extends LitElement {
  @property()
  name = 'a secret';

  render() {
    return html`<p>Hi, my name is ${this.name}!</p>`;
  }
}

class NameTag extends LitElement {
  static properties = {
    name: {},
  };

  constructor() {
    super();
    this.name = 'a secret';
  }

  render() {
    return html`<p>Hi, my name is ${this.name}!</p>`;
  }
}
customElements.define('name-tag', NameTag);

This creates an element you can use anywhere you'd use a regular HTML element:

<name-tag name="Ida"></name-tag>

If you use Web Components already, you'll be happy to hear that they're now natively supported in Chrome, Safari and Firefox. Edge support is coming soon, and polyfills are only needed for legacy browser versions.

If you're new to Web Components, you should give them a try! Web Components let you extend HTML in a way that interoperates with other libraries, tools, and frameworks. This makes them ideal for sharing UI elements within a large organization, publishing components for use anywhere on the web, or building UI design systems like Material Design.

You can use custom elements anywhere you use HTML: in your main document, in a CMS, in Markdown, or in views built with frameworks like React and Vue. You can also mix and match LitElement components with other Web Components, whether they've been written using vanilla web technologies or made with the help of tools like Salesforce Lightning Web Components, Ionic's Stencil, SkateJS or the Polymer library.

Want to try lit-html and LitElement? A good starting point is the LitElement tutorial:

• Try LitElement

If you're interested in using lit-html by itself, or integrating lit-html templating into another project, see the lit-html docs:

• lit-html docs

As always, let us know what you think. You can reach us on Discord or Twitter. Our projects are open source (of course!) and you can report bugs, file feature requests or suggest improvements on GitHub:

• lit-html on GitHub
• LitElement on GitHub