lit-html Templates

Common errors

• ReferenceError: html is not defined

  cause 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

  cause 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

  cause 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.

Warnings

• 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.
• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install lit-html npm
• yarn add lit-html yarn
• pnpm add lit-html pnpm

Imports

• html
  wrong:

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

  correct:

  import { html } from 'lit-html';

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

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

  correct:

  import { render } from 'lit-html';

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

  import { TemplateResult } from 'lit-html';

  correct:

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

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

Quickstart

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);