Getting Started

Create a LitElement component project
Add LitElement to an existing project

There are two main ways to use LitElement:

Creating reusable components to share with other developers. Individual components or sets of related components are usually published to npm. To create a reusable component project, see Create a LitElement component project.
Creating app-specific components. The source for these components may live as part of an application project. To add LitElement components to your app, see Add LitElement to an existing project.

Create a LitElement component project

Get started writing a reusable LitElement component that could be published for others to use.

To get started working on a component locally, you can use one of these starter projects:

Both projects define a LitElement component. They also add a set of optional tools for developing, linting, and testing the component:

Node.js and npm for managing dependencies. Requires Node.js 10 or greater.
A local dev server, ES dev server.
Linting with ESLint and lit-analyzer.
Testing with Karma.
A static doc site built with web component analyzer and eleventy.

None of these tools is required to work with LitElement. They represent one possible set of tools for a good developer experience.

Alternative starting point. As an alternative to the official LitElement starter projects, the open-wc project has a project generator for web components using LitElement. The open-wc script asks a series of questions and scaffolds out a project for you.

Download the starter project

The quickest way to try out a project locally is to download one of the starter projects as a zip file.

Download the starter project from GitHub as a zip file:
- JavaScript starter project
- TypeScript starter project
Uncompress the zip file.
Install dependencies.
```
cd <project folder>
npm i
```

Want it on GitHub? If you’re familiar with git you may want to create a GitHub repository for your starter project, instead of just downloading the zip file. You can use the GitHub template repository feature to create your own repository from the JavaScript starter project or the TypeScript starter project. Then clone your new repository and install dependencies, as above.

Try out your project

If you’re using the TypeScript version of the starter, build the JavaScript version of your project:
```
npm run build
```
To watch files and rebuild when the files are modified, run the following command in a separate shell:
```
npm run build:watch
```
No build step is required if you’re using the JavaScript version of the starter project.
Run the dev server:
```
npm run serve
```
Open the project demo page in a browser tab. For example:

http://localhost:8000/dev/

Your server may use a different port number. Check the URL in the terminal output for the correct port number.

Edit your component

Edit your component definition. The file you edit depends on which language you’re using:

JavaScript. Edit the my-element.js file in the project root.
TypeScript. Edit the my-element.ts file in the src directory.

A couple of things to look for in the code:

The code defines a class for the component (MyElement) and registers it with the browser as a custom element named <my-element>.

JavaScript

export class MyElement extends LitElement { ... } 

customElements.define('my-element', MyElement);

TypeScript

@customElement('my-element')
export class MyElement extends LitElement { ... } 

The component’s render method defines a template that will be rendered as a part of the component. In this case, it includes some text, some data bindings, and a button. For more information, see Templates.

export class MyElement extends LitElement {
  ...
  render() {
    return html`
      <h1>Hello, ${this.name}!</h1>
      <button @click=${this._onClick}>
        Click Count: ${this.count}
      </button>
      <slot></slot>
    `;
  }
}

The component defines some properties. The component responds to changes in these properties (for example, by re-rendering the template when necessary). For more information, see Properties.

JavaScript

export class MyElement extends LitElement {

  static get properties() {
    return {
      name: {type: String}
    }
  }

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

TypeScript

export class MyElement extends LitElement {
  ...
  @property({type: String})
  name = 'World';
  ...
}

Rename your component

You’ll probably want to change the component name from “my-element” to something more appropriate. This is easiest to do using an IDE or other text editor that lets you do a global search and replace through an entire project.

If you’re using the TypeScript version, remove generated files:
```
npm run clean
```
Search and replace “my-element” with your new component name in all files in your project (except in the node_modules folder).
Search and replace “MyElement” with your new class name in all files in your project (except in the node_modules folder).
Rename the source and test files to match the new component name:

JavaScript:
- src/my-element.js
- src/test/my-element_test.js
TypeScript:
- src/my-element.ts
- src/test/my-element_test.ts
If you’re using the TypeScript version, rebuild the project:
```
npm run build
```
Test and make sure your component is still working:
```
npm run serve
```

Next steps

Ready to add features to your new component? Head over to Templates for details on writing templates for your LitElement component.

For details on running tests and using other tools, see the starter project README:

Add LitElement to an existing project

You don’t need a lot of tooling for LitElement projects. Chances are if you have an existing set of tools, you can integrate LitElement into it with very limited changes. These instructions assume you’re using npm for package management, and using a tool like Rollup or webpack to bundle your code for production.

For details on building projects, including some sample Rollup configurations, see Build for production.

If you’re starting from scratch, the open-wc project has a project generator that can scaffold out an application project using LitElement.

Prerequisites

Your build system will need to handle consuming bare module specifiers:

import {LitElement, html} from 'lit-element';

Webpack automatically handles bare module specifiers; for Rollup, you’ll need a plugin (@rollup/plugin-node-resolve).

Install LitElement

LitElement is available from npm:

npm i lit-element

Add an element

Pick a location to store your LitElement components, and create a test element:

components/my-element.js

import {LitElement, html} from 'lit-element';

class MyElement extends LitElement {
  render() {
    return html`
      <div>Hello from MyElement!</div>
    `;
  }
}

customElements.define('my-element', MyElement);

Import your component:

Index.js

import './components/my-elements.js';

Use your component:

index.html

<my-element></my-element>

At this point, you should be able to build and run your project and see the “Hello from MyElement!” message.

Adjust for your build system

How you import the component may vary slightly depending on your build system and project structure. If you’re writing in TypeScript, you’ll use TypeScript files and use LitElement’s decorators. (You can find a sample TypeScript element in the TypeScript starter project).

For more details and sample build configurations, see Build for production.

Optional: Use ES dev server

If you already have a dev server that works with your build system, it should work with LitElement. ES dev server is an alternative dev server that provides a simple, bundler-free workflow. It performs a small number of useful transforms, including transforming bare module specifiers, transpiling to ES5 when needed, and adding polyfills for older browsers.

Install es-dev-server
```
 npm i -D es-dev-server
```

Add a dev server command to package.json:

 {
   "scripts": {
     "serve": "es-dev-server --app-index index.html --node-resolve --watch --open"
   }
 }

Start ES dev server:
```
 npm run serve
```

Supporting older browsers

To support older browsers that don’t support ES6 and the web components specifications, you’ll need to take a few extra steps to produce code that will run on the older browsers.

See Build for production for more information.

Next steps

Ready to add features to your project? Head over to Templates for details on writing templates for your LitElement component.

For more on building applications that use web components, see the open-wc recommendations on Building.