Getting Started

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

Setup

You need npm and Node.js to work with LitElement. To install npm and Node.js, see the instructions on NodeJS.org.

LitElement uses JavaScript modules to import dependencies by their npm package names. Since web browsers need to know a file’s full URL to import it, your local development server needs to serve full, transformed URL paths to your web browser.

To deploy an optimized build that works on your target browsers, you’ll also need a build toolset that can handle this transform, along with any bundling.

One option is Polymer CLI, which includes a development server that converts module names to paths on the fly; and a configurable build tool that packages your code for deployment.

To install Polymer CLI with npm:

npm install -g polymer-cli

To serve a LitElement project locally:

polymer serve

See the Polymer CLI documentation for more information on configuring these tools.

Read on to create a component, or download a sample LitElement project.

Create a LitElement component

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);