lit

A library for building fast, lightweight web components

weekly downloads4.2M

versionv3.3.2

licenseBSD-3-Clause

categoryfrontend

Overview

Lit is a lightweight (~5KB) library that streamlines the development of native Web Components by providing a reactive programming model, declarative templating system, and scoped styling capabilities. Built on top of Web Standards, it wraps the complexity of native APIs while maintaining full compatibility with the browser's Web Component specifications.

The library addresses the verbosity and boilerplate required when building Web Components directly with native APIs. While the Custom Elements specification is powerful, raw implementations require manual DOM manipulation, verbose property/attribute synchronization, and careful lifecycle management. Lit provides decorators, automatic re-rendering on property changes, and a template literal-based rendering system that makes component authoring feel more like modern framework development.

With over 4 million weekly downloads, Lit powers design systems and component libraries at organizations requiring framework-agnostic UI components. Since Lit components compile to standard Web Components, they work seamlessly in React, Vue, Angular, or vanilla JavaScript projects without wrappers or adapters. The library consists of modular packages—lit-html for templating and ReactiveElement for the base class—allowing developers to use only what they need or even mix Lit with other Web Component libraries on the same page.

Quick Start

typescript

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

class CounterButton extends LitElement {
  static styles = css`
    :host {
      display: inline-block;
    }
    button {
      padding: 8px 16px;
      font-size: 16px;
      background: #0066cc;
      color: white;
      border: none;
      border-radius: 4px;
      cursor: pointer;
    }
    button:hover {
      background: #0052a3;
    }
    .count {
      margin-left: 8px;
      font-weight: bold;
    }
  `;

  @property({ type: String })
  label = 'Count';

  @state()
  private count = 0;

  private increment() {
    this.count++;
    this.dispatchEvent(new CustomEvent('count-changed', {
      detail: { count: this.count },
      bubbles: true,
      composed: true
    }));
  }

  render() {
    return html`
      <button @click=${this.increment}>
        ${this.label}:
        <span class="count">${this.count}</span>
      </button>
    `;
  }
}

customElements.define('counter-button', CounterButton);

Use Cases

Design System Components: Build a company-wide component library that works across multiple framework codebases. Lit components publish to npm as standard ES modules and integrate into React apps, Angular projects, and vanilla sites without modification.

Micro-Frontend Architecture: Create isolated UI widgets that different teams can embed regardless of their framework choice. A Lit-based data table or date picker can be dropped into any application as a standard HTML element.

Progressive Enhancement: Add interactive islands to server-rendered HTML without committing to a full framework. Lit components hydrate efficiently and can enhance existing markup with client-side interactivity.

Component Migration Strategy: Gradually replace legacy jQuery or Polymer components with modern Web Components. Lit's small bundle size and framework independence make it ideal for incremental migrations where rewriting entire applications isn't feasible.

Browser Extension UI: Build extension popups and options pages with reactive components that don't carry the weight of larger frameworks. Lit's minimal footprint is critical in extension environments where bundle size directly impacts user experience.

Pros & Cons

Pros

+Extremely small bundle size (5KB) with no virtual DOM overhead, leading to fast initial load and runtime performance
+True framework interoperability—components work natively in React, Vue, Angular, or vanilla JS without wrappers or integration code
+Direct access to Web Standards (Custom Elements, Shadow DOM) without framework lock-in, ensuring long-term viability
+Excellent TypeScript support with decorators that make property declarations and lifecycle hooks type-safe and readable
+Modular architecture allows using lit-html templating independently from the full LitElement base class

Cons

−Smaller ecosystem compared to React or Vue—fewer third-party component libraries and less community content available
−Learning curve for developers unfamiliar with Web Component concepts like Shadow DOM, slots, and custom events
−Custom DSL introduces Lit-specific patterns (html tagged templates, @property decorators) that differ from plain JavaScript
−Shadow DOM encapsulation can complicate integration with global styles, theme systems, or CSS frameworks expecting global scope
−Server-side rendering support exists but is more complex than established framework SSR solutions

Alternatives

preactv10.28.3

Fast 3kb React-compatible Virtual DOM library.

frontendpreactreact

11.5M / week

sveltev5.53.0

Cybernetically enhanced web apps

frontendsvelteUI

2.7M / week

Install

bash

npm install lit

bash

pnpm add lit

bash

bun add lit

Overview

Quick Start

typescript

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

class CounterButton extends LitElement {
  static styles = css`
    :host {
      display: inline-block;
    }
    button {
      padding: 8px 16px;
      font-size: 16px;
      background: #0066cc;
      color: white;
      border: none;
      border-radius: 4px;
      cursor: pointer;
    }
    button:hover {
      background: #0052a3;
    }
    .count {
      margin-left: 8px;
      font-weight: bold;
    }
  `;

  @property({ type: String })
  label = 'Count';

  @state()
  private count = 0;

  private increment() {
    this.count++;
    this.dispatchEvent(new CustomEvent('count-changed', {
      detail: { count: this.count },
      bubbles: true,
      composed: true
    }));
  }

  render() {
    return html`
      <button @click=${this.increment}>
        ${this.label}:
        <span class="count">${this.count}</span>
      </button>
    `;
  }
}

customElements.define('counter-button', CounterButton);

Use Cases

Pros & Cons

Pros

+Extremely small bundle size (5KB) with no virtual DOM overhead, leading to fast initial load and runtime performance
+True framework interoperability—components work natively in React, Vue, Angular, or vanilla JS without wrappers or integration code
+Direct access to Web Standards (Custom Elements, Shadow DOM) without framework lock-in, ensuring long-term viability
+Excellent TypeScript support with decorators that make property declarations and lifecycle hooks type-safe and readable
+Modular architecture allows using lit-html templating independently from the full LitElement base class

Cons

−Smaller ecosystem compared to React or Vue—fewer third-party component libraries and less community content available
−Learning curve for developers unfamiliar with Web Component concepts like Shadow DOM, slots, and custom events
−Custom DSL introduces Lit-specific patterns (html tagged templates, @property decorators) that differ from plain JavaScript
−Shadow DOM encapsulation can complicate integration with global styles, theme systems, or CSS frameworks expecting global scope
−Server-side rendering support exists but is more complex than established framework SSR solutions