lit-element

What is lit-element?

The lit-element package is a simple base class for creating fast, lightweight web components with the Lit library. It provides a declarative template system that ties your markup to your component's properties and state, along with reactive updates and a component lifecycle.

What are lit-element's main functionalities?

Declarative Templates

LitElement uses `html` tagged template literals to define templates that are bound to the component's properties. When properties change, the template is efficiently re-rendered.

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

class MyElement extends LitElement {
  static get properties() {
    return {
      message: { type: String }
    };
  }

  constructor() {
    super();
    this.message = 'Hello, World!';
  }

  render() {
    return html`<p>${this.message}</p>`;
  }
}
customElements.define('my-element', MyElement);

Reactive Properties

Properties can be made reactive using the `@property` decorator. When a reactive property changes, LitElement automatically updates the component's template.

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

class MyElement extends LitElement {
  @property({ type: String }) greeting = 'Hello';

  render() {
    return html`<h1>${this.greeting}, World!</h1>`;
  }
}
customElements.define('my-element', MyElement);

Lifecycle Methods

LitElement provides lifecycle methods such as `firstUpdated`, `updated`, and `disconnectedCallback` for managing the component's lifecycle events.

import { LitElement } from 'lit-element';

class MyElement extends LitElement {
  firstUpdated(changedProperties) {
    console.log('Component first updated!');
  }

  updated(changedProperties) {
    console.log('Component updated with changed properties:', changedProperties);
  }

  disconnectedCallback() {
    console.log('Component removed from the DOM!');
  }
}
customElements.define('my-element', MyElement);

Other packages similar to lit-element

react

React is a popular library for building user interfaces. It uses a virtual DOM for efficient updates, which is different from LitElement's direct DOM manipulation. React components are typically more verbose and use JSX for templating.

vue

Vue is a progressive framework for building UIs. Like LitElement, it offers a reactive and composable data model. Vue uses a virtual DOM similar to React and has a more opinionated structure, including a focus on single-file components.

svelte

Svelte is a compiler that generates efficient JavaScript code for creating web components. Unlike LitElement, which updates the DOM in response to property changes, Svelte compiles components to update the DOM directly, which can result in better performance for some applications.

stencil

Stencil is a compiler that generates web components with a focus on performance and compatibility. It provides a set of features similar to LitElement but includes a virtual DOM and TypeScript support out of the box.

README

LitElement 3.0 Pre-release

🚨 About this pre-release

This is a major version pre-release of LitElement 3.0. See issue #1077 for the full list of changes planned/considered for this release.

This pre-release is not yet feature complete or API stable. Please note the breaking changes, known issues, and limitations below, and use at your risk until the stable release is available. Issues are welcome for unexpected changes not noted below or in the changelog.

🚨 Breaking changes

While LitElement 3.0 is intended to be a mostly backward-compatible change for the majority of 2.x users, please be aware of the following notable breaking changes:

• This LitElement pre-release uses the lit-html pre-release as well. Please see the lit-html pre-release README and changelog for information on any breaking changes to lit-html features in your components.
• Decorators are no longer exported from the top-level lit-element module. Instead, import any decorators you use from lit-element/decorators/*.
• requestUpdate() no longer returns a Promise. Instead await the updateComplete Promise.

See the full changelog for more details on these and other minor breaking changes.

🚨 Known issues/limitations

• Browser support: This pre-release should run on modern browsers, however a change to factor legacy browser support (IE11, etc.) into an opt-in package is ongoing. As such, this release will not run on some older browsers. This is a temporary state.
• lit-html limitations: Some features of lit-html are still in progress. Please refer to the pre-release README for a list of known lit-html issues.

---

LitElement

A simple base class for creating fast, lightweight web components with lit-html.

Documentation

Full documentation is available at lit-element.polymer-project.org.

Overview

LitElement uses lit-html to render into the element's Shadow DOM and adds API to help manage element properties and attributes. LitElement reacts to changes in properties and renders declaratively using lit-html. See the lit-html guide for additional information on how to create templates for lit-element.

import {LitElement, html, css} from 'lit-element';
import {customElement, property} from 'lit-element/decorators.js';

// This decorator defines the element.
@customElement('my-element')
export class MyElement extends LitElement {
  // This decorator creates a property accessor that triggers rendering and
  // an observed attribute.
  @property()
  mood = 'great';

  static styles = css`
    span {
      color: green;
    }
  `;

  // Render element DOM by returning a `lit-html` template.
  render() {
    return html`Web Components are <span>${this.mood}</span>!`;
  }
}

<my-element mood="awesome"></my-element>

Note, this example uses decorators to create properties. Decorators are a proposed standard currently available in TypeScript or Babel. LitElement also supports a vanilla JavaScript method of declaring reactive properties.

Examples

• Runs in all supported browsers: Glitch

• Runs in browsers with JavaScript Modules: Stackblitz, JSFiddle, JSBin, CodePen.

• You can also copy this HTML file into a local file and run it in any browser that supports JavaScript Modules.

Installation

From inside your project folder, run:

$ npm install lit-element

To install the web components polyfills needed for older browsers:

$ npm i -D @webcomponents/webcomponentsjs

Development mode

lit-element includes a development mode which adds additional checks that are reported in the console.

To enable development mode, add the development exports condition to your node resolve configuration.

@web/dev-server

NOTE: Requires rollup#540

{
  nodeResolve: {
    exportConditions: ['development'];
  }
}

Rollup

NOTE: Requires rollup#540

{
  plugins: [
    nodeResolve({
      exportConditions: ['development'],
    }),
  ];
}

Webpack

NOTE: Requires Webpack v5

{
  resolve: {
    conditionNames: ['development'];
  }
}

Supported Browsers

The last 2 versions of all modern browsers are supported, including Chrome, Safari, Opera, Firefox, Edge. In addition, Internet Explorer 11 is also supported.

Edge and Internet Explorer 11 require the web components polyfills.

Contributing

Please see CONTRIBUTING.md.