@lit/reactive-element

What is @lit/reactive-element?

The @lit/reactive-element package provides a base class for creating lightweight, reactive components. It is part of the Lit library, which is designed for building fast, lightweight web components. The reactive-element package focuses on the reactive system that powers Lit components, allowing developers to create and manage properties that automatically update the component when changed.

What are @lit/reactive-element's main functionalities?

Reactive properties

This feature allows the creation of reactive properties that trigger updates to the component when their values change. The example defines a custom element with a reactive property 'name'. When 'name' changes, the 'updated' method logs the new value.

import { ReactiveElement } from '@lit/reactive-element';

class MyElement extends ReactiveElement {
  static properties = {
    name: {type: String}
  };

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

  updated(changedProperties) {
    if (changedProperties.has('name')) {
      console.log(`Name updated to: ${this.name}`);
    }
  }
}
customElements.define('my-element', MyElement);

Lifecycle callbacks

Lifecycle callbacks provide hooks into the component's lifecycle. This example shows how to use 'connectedCallback' and 'disconnectedCallback' to perform actions when the element is added to or removed from the DOM.

import { ReactiveElement } from '@lit/reactive-element';

class MyElement extends ReactiveElement {
  connectedCallback() {
    super.connectedCallback();
    console.log('Element added to the page.');
  }

  disconnectedCallback() {
    super.disconnectedCallback();
    console.log('Element removed from the page.');
  }
}
customElements.define('my-element', MyElement);

Other packages similar to @lit/reactive-element

react

React is a popular library for building user interfaces. It uses a virtual DOM for efficient updates, similar to how @lit/reactive-element uses reactive properties to manage updates. However, React is generally used for larger applications and offers a more comprehensive ecosystem of tools and extensions.

vue

Vue is another popular framework that provides reactive components. Like @lit/reactive-element, Vue components automatically update when reactive data changes. Vue offers a more integrated solution with built-in directives and a more opinionated structure, which differs from the minimalistic and low-level approach of @lit/reactive-element.

README

ReactiveElement 1.0

ReactiveElement

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

About this release

This is a pre-release of Lit 3.0, the next major version of Lit.

Lit 3.0 has very few breaking changes from Lit 2.0:

• Drops support for IE11
• Published as ES2021
• Removes a couple of deprecated Lit 1.x APIs

Lit 3.0 should require no changes to upgrade from Lit 2.0 for the vast majority of users. Once the full release is published, most apps and libraries will be able to extend their npm version ranges to include both 2.x and 3.x, like "^2.7.0 || ^3.0.0".

Lit 2.x and 3.0 are interoperable: templates, base classes, directives, decorators, etc., from one version of Lit will work with those from another.

Please file any issues you find on our issue tracker.

Documentation

Full documentation is available at lit.dev.

Overview

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.

Example

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.

Installation

$ npm install @lit/reactive-element

Or use from lit:

$ npm install lit

Contributing

Please see CONTRIBUTING.md.