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

lit-element

Implements lit-html via a LitElement class. Made for custom Elements.

New in 0.4.0

• We now allow you to switch out the standard lit-html render and html functions
• You can now use lit-html-extended via lit-element-extended.js
• Added notify option for properties, which will fire an event, if the value changes
• A lot of bug fixes

New in 0.3.0

• You can now set any property of your element to a promise and LitElement will set the property to the resolved value of the promise. (credit: depeele)
• Attributes of properties with reflectToAttribute: true are now transformed to kebab-case. (credit: depeele)
• Codebase moved to TypeScript.

Installation

You can get it through npm or yarn

npm install lit-element

yarn add lit-element

Default Usage

// import lit-element
import {LitElement, html} from '../node_modules/lit-element/lit-element.js'

// define Custom Element
class MyElement extends LitElement(HTMLElement) {

    // define properties similiar to Polymer 2/3
    static get properties() {
        return {
            title: String,
            body: {
                type: String,
                value: 'That is a cool LitElement',
                observer: '_bodyChanged',
                reflectToAttribute: true,
                notify: true
            }
        }
    }
    
    // define your template in render
    render() {
        this.title = 'This is lit';
        return html`
            <h1 id="title">${this.title}</h1>
            <p>${this.body}</h1>
        `;
    }

    // observer callback
    _bodyChanged(newValue) {
        console.log(`Body updated to ${newValue}`);
    }

    // If you want work done after the first render, like accessing elements with ids, do it here
    afterRender(isFirstRender) {
        if(isFirstRender) {
            // access the element with id 'title'
            this.$.title.classList.add('title--main');
            this.addEventListener('body-changed', e => {
                const body = e.detail;
                ...
            })
        }
    }
}

Declaring properties

Properties of your element are set through a static getter of properties, as seen above.

Properties can be set with the following options:

• type: The type function of this property. Must be set!
• reflectToAttribute: Keeps the property in sync with the attribute of the same name, konverted to kebab-case (myProp <-> my-prop)
• value: The initial value of the property. If it should be an array or an object, set value to a function returning that object, to keep it unique for each instance of the element
• observer: The name of the method that should be called whenever the property changes.
• notify: Dispatch an event on property-change. The event name follows the pattern my-prop-changed. The new value is in event.detail.

Notes

• This Element does not use Polymer, just Polymer-like syntax for properties.
• Currently only type, reflectToAttribute, observer, value and notify are supported for properties.