Lit Architecture: lit-element vs lit-html

Both lit-element and lit-html are foundational pieces of the Lit library suite, designed to make building Web Components fast and reliable. While they share the same core rendering engine, they solve different problems in the component stack. It is important to note that modern development should target the unified lit package, but understanding the distinction helps when maintaining older codebases.

🎯 Core Purpose: Rendering Engine vs Component Base

lit-html is strictly a view layer.

• It renders templates into DOM nodes.
• It does not manage state or lifecycle events.
• Best for simple UI updates or custom rendering logic.

// lit-html: Direct rendering
import { html, render } from 'lit-html';

const template = (name) => html`<p>Hello ${name}</p>`;
render(template('World'), document.body);

lit-element is a full Web Component base class.

• It extends HTMLElement to create custom tags.
• It includes state management and lifecycle hooks.
• Best for building reusable, encapsulated components.

// lit-element: Component class
import { LitElement, html } from 'lit-element';

class MyElement extends LitElement {
  render() {
    return html`<p>Hello World</p>`;
  }
}
customElements.define('my-element', MyElement);

🧠 State Management: None vs Reactive Properties

lit-html has no built-in state system.

• You must pass data manually into template functions.
• Changes require calling render() again with new data.
• Good for functional-style UI updates.

// lit-html: Manual data passing
let count = 0;
const update = () => {
  count++;
  render(html`<div>${count}</div>`, container);
};

lit-element has a reactive property system.

• Define properties using a static getter or decorators.
• The component re-renders automatically when data changes.
• Reduces boilerplate for state-driven UIs.

// lit-element: Reactive properties
import { property } from 'lit-element/decorators.js';

class Counter extends LitElement {
  @property({ type: Number }) count = 0;

  render() {
    return html`<div>${this.count}</div>`;
  }
}

🔄 Lifecycle: Manual vs Built-In Hooks

lit-html offers no lifecycle hooks.

• You manage setup and cleanup outside the render function.
• You must manually attach event listeners or observers.
• More control but more code to maintain.

// lit-html: Manual setup
function init() {
  const sub = subscribe(data => {
    render(html`<div>${data}</div>`, container);
  });
  return () => sub.unsubscribe(); // Manual cleanup
}

lit-element provides standard lifecycle methods.

• Use connectedCallback, updated, or disconnectedCallback.
• Hooks integrate with the reactive update cycle.
• Easier to manage side effects like API calls.

// lit-element: Lifecycle hooks
class UserData extends LitElement {
  updated() {
    console.log('Component updated');
  }

  disconnectedCallback() {
    super.disconnectedCallback();
    // Cleanup logic here
  }
}

📦 The Modern Unified Package

Starting with Lit 2.0, the team merged these libraries into one package called lit.

• You import LitElement and html from 'lit'.
• This reduces dependency count and simplifies versioning.
• Legacy packages remain available but are not recommended for new work.

// Modern lit: Unified import
import { LitElement, html } from 'lit';

class ModernElement extends LitElement {
  render() {
    return html`<div>Using unified package</div>`;
  }
}

🤝 Similarities: Shared Ground Between lit-element and lit-html

While their roles differ, both libraries share core technologies and principles.

1. 📝 Tagged Template Literals

• Both use the html tag function to define templates.
• Syntax highlighting and linting work similarly in editors.

// lit-html template
const view = html`<div>Content</div>`;

// lit-element template
render() { return html`<div>Content</div>`; }

2. ⚡ Efficient DOM Updates

• Both use a virtual DOM-like diffing algorithm.
• Only changed parts of the DOM are updated on re-render.
• Ensures high performance for dynamic interfaces.

// Both: Efficient binding updates
html`<div>${dynamicValue}</div>`; // Only text node updates

3. 🌐 Web Standards Focus

• Both rely on native browser features like Custom Elements.
• No heavy runtime abstraction or custom virtual DOM.
• Works well with other frameworks and libraries.

// Both: Standard Custom Elements API
customElements.define('my-element', MyClass);

4. 🛡️ Security Defaults

• Both escape values by default to prevent XSS attacks.
• Developers must explicitly opt-in for unsafe HTML.
• Protects applications from common injection vulnerabilities.

// Both: Safe by default
html`<div>${userInput}</div>`; // Escaped automatically

5. 🔌 TypeScript Support

• Both ship with full TypeScript definitions included.
• Decorators and properties are strongly typed.
• Enhances developer experience in large codebases.

// Both: TypeScript decorators
@property({ type: String }) name: string = '';

📊 Summary: Key Similarities

🆚 Summary: Key Differences

💡 The Big Picture

lit-html is like a paintbrush 🖌️ — it puts pixels on the canvas but doesn't know about the picture structure. Use it for low-level rendering tasks or when you need maximum flexibility without component overhead.

lit-element is like a framed canvas 🖼️ — it provides structure, state, and lifecycle around the rendering. Use it when building reusable UI components that need to manage their own data.

Final Thought: For any new project, skip the decision entirely and use the unified lit package. It combines the best of both libraries into a single, maintained dependency. Reserve lit-element and lit-html specific imports for maintaining older codebases where migration is not yet feasible.