lit-html

library3.3.2jsnpmunverified

lit-html is a concise and efficient JavaScript library for creating declarative HTML templates using standard JavaScript template literals. It enables developers to render and dynamically update DOM with high performance, as it only modifies the specific parts of the DOM that have changed, avoiding the overhead of a virtual DOM. Currently at version 3.3.2, lit-html is actively maintained as a core part of the Lit project, which focuses on building fast and lightweight web components. It differentiates itself through its tight integration with native browser APIs, small bundle size, and a highly optimized rendering engine. While it can be used standalone, most users developing web components with the Lit library are encouraged to import its functionalities through the main `lit` package for a more integrated development experience. Its release cadence typically aligns with the broader Lit ecosystem updates, often seeing patch releases and minor versions together.

web-framework

npm install lit-html

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LIT-HTML

lit-html

web-frameworkjavascriptv3.3.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

html

✓ import { html } from 'lit-html';

✗ const html = require('lit-html').html;

The `html` tag function is the primary way to define templates. Lit 2.0+ is ESM-only.

render

✓ import { render } from 'lit-html';

✗ const render = require('lit-html').render;

The `render` function attaches a template result to a DOM container. Lit 2.0+ is ESM-only.

TemplateResult

✓ import type { TemplateResult } from 'lit-html';

✗ import { TemplateResult } from 'lit-html';

Used for type-checking template results in TypeScript, not for runtime instantiation.

Demonstrates defining a dynamic lit-html template with event handling and efficiently updating the DOM.

import { html, render } from 'lit-html'; // Define a template function that returns a lit-html TemplateResult const greetingTemplate = (name, count) => html` <div> <h1>Hello, ${name}!</h1> <p>You have clicked the button ${count} times.</p> <button @click=${() => updateCount(name, count + 1)}>Click Me</button> </div> `; let currentCount = 0; // Function to update the count and re-render the template function updateCount(name, newCount) { currentCount = newCount; render(greetingTemplate(name, currentCount), document.body); } // Initial render to the document body updateCount('World', 0);

Debug

Known issues

breaking`lit-html` moved to being ESM-only. CommonJS `require()` is no longer supported for importing modules.

fix

Update imports to use ES module syntax (e.g., `import { html, render } from 'lit-html';`). Ensure your build setup correctly handles ESM.

affects: >=2.0.0

breakingLit 3.0 (and by extension lit-html 3.0) removed many deprecated APIs and required TypeScript 5.0 or newer. Node.js 16 support was also dropped.

fix

Review the Lit 3.0 upgrade guide for specific API changes. Ensure your project uses TypeScript 5.0+ and Node.js 18+ for development and build environments.

affects: >=3.0.0

gotchaDirectly manipulating DOM elements within a container managed by `lit-html` can lead to unexpected behavior and template desynchronization, as `lit-html` manages the lifecycle and updates of its DOM nodes.

fix

Always update the data passed to your lit-html templates and let `render()` handle the DOM updates. Avoid direct DOM manipulation for elements within a `lit-html` rendered scope.

affects: >=1.0.0

gotchaMixing `lit-html` template rendering with other client-side rendering libraries (e.g., React, Vue) in the same DOM container without careful isolation can lead to conflicts and unpredictable UI behavior.

fix

Ensure distinct DOM containers are used for different rendering libraries. If integrating with web components, use the component's shadow DOM to encapsulate `lit-html` rendering.

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: html is not defined

The `html` tag function was not imported or is not in scope.

fix

Add `import { html } from 'lit-html';` to the top of your module.

TypeError: render is not a function

The `render` function was not imported, imported incorrectly, or you are trying to use a CommonJS `require()` import in a modern ESM project.

fix

Ensure `import { render } from 'lit-html';` is used. If using CommonJS, verify your environment supports it or migrate to ESM.

Uncaught SyntaxError: Cannot use import statement outside a module

Your JavaScript file is being loaded as a script, but it uses ES module syntax (e.g., `import` statements).

fix

Add `type="module"` to your script tag in HTML (e.g., `<script type="module" src="./my-app.js"></script>`) or ensure your build process correctly transpiles and bundles for your target environment.

Upgrade

Version history

3.3.2latest on npm

Audit

Dependencies

litoptionalMost users creating web components are encouraged to import lit-html features via the main 'lit' package for an integrated experience.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/lit/lit ↗

packagehttps://www.npmjs.com/package/lit-html ↗

homepagehttps://lit.dev/ ↗