Introduction

This documentation is a work in progress. It describes prerelease software, and is subject to change.

What is LitElement?

LitElement is a simple base class for creating fast, lightweight web components that work in any web page with any framework.

For rendering, LitElement uses lit-html—a fast HTML templating library. To build an app out of LitElement components, check out PWA Starter Kit.

Create a LitElement component

To add LitElement to your project, install the @polymer/lit-element package with npm:

npm install @polymer/lit-element --save

To create a new class based on LitElement:

For example:

my-element.js

// Import the LitElement base class and html helper function
import { LitElement, html } from '@polymer/lit-element';

// Extend the LitElement base class
class MyElement extends LitElement {

  /**
   * Implement `render` to define a template for your element.
   * 
   * You must provide an implementation of `render` for any element
   * that uses LitElement as a base class.
   */
  render(){
    /** 
     * `render` must return a lit-html `TemplateResult`. 
     *
     * To create a `TemplateResult`, tag a JavaScript template literal
     * with the `html` helper function: 
     */
    return html`
      <!-- template content -->
      <p>A paragraph</p>
    `;
  }
}
// Register the new element with the browser.
customElements.define('my-element', MyElement);

Use LitElement TypeScript decorators

You can use the @customElement TypeScript decorator to define your class as a custom element:

/**
 * Import LitElement base class, html helper function,
 * and TypeScript decorators 
 **/
import { 
  LitElement, html, customElement, property 
} from '@polymer/lit-element';

/**
 * Use the customElement decorator to define your class as
 * a custom element. Registers <my-element> as an HTML tag.
 */
@customElement('my-element')
export class MyElement extends LitElement {
  
  /**
   * Create an observed property. Triggers update on change.
   */
  @property()
  foo = 'foo';

  /**
   * Implement `render` to define a template for your element.
   */
  render(){
    /**
     * Use JavaScript expressions to include property values in
     * the element template. 
     */
    return html`<p>${this.foo}</p>`;
  }
}

Import a component

Import your own LitElement component

In an HTML document:

<head>
  <script type="module" src="/path/to/my-element.js"></script>
</head>
<body>
  <my-element></my-element>
</body>

In another JavaScript module:

// Use relative paths for peer dependencies
import './my-element.js';

class MyOtherElement extends LitElement{
  render(){
    return html`
      <my-element></my-element>
    `;
  }
}
customElements.define('my-other-element', MyOtherElement);

Import a third-party LitElement component

Refer to third-party component documentation first. To work with any existing component made by a third party, see its documentation. This guide should work for most LitElement-based components if they are published on npm.

Many components are published on npm and can be installed from the command line:

cd my-project-folder
npm install package-name --save

In an HTML document, a component published on npm can be imported from the node_modules folder:

<head>
  <script type="module" src="node_modules/package-name/existing-element.js"></script>
</head>
<body>
  <existing-element></existing-element>
</body>

To import into another JavaScript module, use the component’s package name:

import 'package-name/existing-element.js';

class MyElement extends LitElement{
  render(){
    return html`
      <existing-element></existing-element>
    `;
  }
}
customElements.define('my-element', MyElement);