{"id":11243,"library":"lit-html","title":"lit-html Templates","description":"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.","status":"active","version":"3.3.2","language":"javascript","source_language":"en","source_url":"https://github.com/lit/lit","tags":["javascript","typescript"],"install":[{"cmd":"npm install lit-html","lang":"bash","label":"npm"},{"cmd":"yarn add lit-html","lang":"bash","label":"yarn"},{"cmd":"pnpm add lit-html","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Most users creating web components are encouraged to import lit-html features via the main 'lit' package for an integrated experience.","package":"lit","optional":true}],"imports":[{"note":"The `html` tag function is the primary way to define templates. Lit 2.0+ is ESM-only.","wrong":"const html = require('lit-html').html;","symbol":"html","correct":"import { html } from 'lit-html';"},{"note":"The `render` function attaches a template result to a DOM container. Lit 2.0+ is ESM-only.","wrong":"const render = require('lit-html').render;","symbol":"render","correct":"import { render } from 'lit-html';"},{"note":"Used for type-checking template results in TypeScript, not for runtime instantiation.","wrong":"import { TemplateResult } from 'lit-html';","symbol":"TemplateResult","correct":"import type { TemplateResult } from 'lit-html';"}],"quickstart":{"code":"import { html, render } from 'lit-html';\n\n// Define a template function that returns a lit-html TemplateResult\nconst greetingTemplate = (name, count) => html`\n  <div>\n    <h1>Hello, ${name}!</h1>\n    <p>You have clicked the button ${count} times.</p>\n    <button @click=${() => updateCount(name, count + 1)}>Click Me</button>\n  </div>\n`;\n\nlet currentCount = 0;\n\n// Function to update the count and re-render the template\nfunction updateCount(name, newCount) {\n  currentCount = newCount;\n  render(greetingTemplate(name, currentCount), document.body);\n}\n\n// Initial render to the document body\nupdateCount('World', 0);\n","lang":"typescript","description":"Demonstrates defining a dynamic lit-html template with event handling and efficiently updating the DOM."},"warnings":[{"fix":"Update imports to use ES module syntax (e.g., `import { html, render } from 'lit-html';`). Ensure your build setup correctly handles ESM.","message":"`lit-html` moved to being ESM-only. CommonJS `require()` is no longer supported for importing modules.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"Lit 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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"Directly 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Mixing `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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Add `import { html } from 'lit-html';` to the top of your module.","cause":"The `html` tag function was not imported or is not in scope.","error":"ReferenceError: html is not defined"},{"fix":"Ensure `import { render } from 'lit-html';` is used. If using CommonJS, verify your environment supports it or migrate to ESM.","cause":"The `render` function was not imported, imported incorrectly, or you are trying to use a CommonJS `require()` import in a modern ESM project.","error":"TypeError: render is not a function"},{"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.","cause":"Your JavaScript file is being loaded as a script, but it uses ES module syntax (e.g., `import` statements).","error":"Uncaught SyntaxError: Cannot use import statement outside a module"}],"ecosystem":"npm"}