This is a major version pre-release of ReactiveElement 1.0. This package has been migrated out of LitElement. See issue #1077 for more info.

This pre-release is not yet feature complete or API stable.

A simple low level base class for creating fast, lightweight web components.

Full documentation is available at lit.dev.

ReactiveElement is a base class for writing web components that react to changes in properties and attributes. ReactiveElement adds reactive properties and a batching, asynchronous update lifecycle to the standard web component APIs. Subclasses can respond to changes and update the DOM to reflect the element state.

ReactiveElement doesn't include a DOM template system, but can easily be extended to add one by overriding the update() method to call the template library. LitElement is such an extension that adds lit-html templating.

import {
  ReactiveElement,
  html,
  css,
  customElement,
  property,
  PropertyValues,
} from '@lit/reactive-element';

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

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

  contentEl?: HTMLSpanElement;

  // One time setup of shadowRoot content.
  createRenderRoot() {
    const shadowRoot = super.createRenderRoot();
    shadowRoot.innerHTML = `Web Components are <span></span>!`;
    this.contentEl = shadowRoot.firstElementChild;
    return shadowRoot;
  }

  // Use a DOM rendering library of your choice or manually update the DOM.
  update(changedProperties: PropertyValues) {
    super.update(changedProperties);
    this.contentEl.textContent = this.mood;
  }
}

<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. ReactiveElement also supports a vanilla JavaScript method of declaring reactive properties.

From inside your project folder, run:

$ npm install @lit/reactive-element

To install the web components polyfills needed for older browsers:

$ npm i -D @webcomponents/webcomponentsjs

@lit/reactive-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.

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

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

NOTE: Requires Webpack v5

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

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 and the polyfill-support module included in this package.

<script src="node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js"></script>
<script src="node_modules/@lit/reactive-element/polyfill-support.js"></script>
<!-- load application code -->

Please see CONTRIBUTING.md.