lit-html

API reference for the lit-html library — efficient, expressive HTML templating for the browser.

lit-html is Lit’s HTML templating library. It lets you write HTML templates in JavaScript using tagged template literals and efficiently renders and updates DOM.

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

Template tags

html

Interprets a template literal as an HTML template.

export const html: (strings: TemplateStringsArray, ...values: unknown[]) => HTMLTemplateResult

const header = (title: string) => html`<h1>${title}</h1>`;

Returns an HTMLTemplateResult. Templates are lazy — no DOM is created until render() is called. Subsequent renders to the same container efficiently update only the changed parts.

svg

Interprets a template literal as an SVG fragment.

export const svg: (strings: TemplateStringsArray, ...values: unknown[]) => SVGTemplateResult

const rect = svg`<rect width="10" height="10"></rect>`;

const myImage = html`
  <svg viewBox="0 0 10 10" xmlns="http://www.w3.org/2000/svg">
    ${rect}
  </svg>`;

Use svg only for content that belongs inside an <svg> element, not for the <svg> element itself. The <svg> element is an HTML element and belongs in an html-tagged template.

mathml

Interprets a template literal as a MathML fragment.

export const mathml: (strings: TemplateStringsArray, ...values: unknown[]) => MathMLTemplateResult

Rendering

render(value, container, options?)

Renders a value to a DOM container. The first render appends content to the container; subsequent renders efficiently update in place.

export const render: (
  value: unknown,
  container: HTMLElement | SVGElement | DocumentFragment,
  options?: RenderOptions
) => RootPart

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

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

value · unknown · required

Any renderable value. Typically a TemplateResult from html or svg, but also strings, numbers, nothing, DOM nodes, arrays, or iterables.

container · HTMLElement | SVGElement | DocumentFragment · required

The DOM container to render into. Only the options passed during the first render to a container + renderBefore pair are used for the lifetime of that render.

options · RenderOptions

Controls rendering behavior. See RenderOptions below.

returns · RootPart

A RootPart for the rendered tree. Call part.setConnected(false) before discarding to allow AsyncDirectives to dispose of resources.

RenderOptions

Options that control how render behaves. Only options passed during the first render to a given container + renderBefore pair take effect.

host · object

Object used as this when calling event listener functions. Commonly set to the host component instance.

renderBefore · ChildNode | null

A DOM node before which to render content in the container. Use to control insertion position.

creationScope · { importNode(node: Node, deep?: boolean): Node }

Node used for cloning templates via importNode. Controls the ownerDocument of the rendered DOM and any inherited context. Defaults to the global document.

isConnected · boolean

Initial connected state for the top-level part. Defaults to true. Set to false when the initial render occurs in a disconnected tree so that AsyncDirectives see isConnected === false on their first render.

Sentinels

noChange

export const noChange: unique symbol  // Symbol.for('lit-noChange')

A sentinel value that signals a directive has handled a value and nothing should be written to the DOM. Returning noChange from a directive leaves the previously committed value in place.

nothing

export const nothing: unique symbol  // Symbol.for('lit-nothing')

A sentinel value that clears a part’s content.

const button = html`${
  user.isAdmin
    ? html`<button>DELETE</button>`
    : nothing
}`;

Context	Effect
Child expression	Renders no nodes (same as null, undefined, '')
Attribute expression	Removes the attribute entirely
Property expression	Sets the property to undefined

Prefer nothing over other falsy values for consistent behavior across expression types.

TemplateResult types

TemplateResult<T>

The return type of html, svg, and mathml. Holds the template strings, expression values, and result type. Does not create DOM on its own — DOM is created when the result is passed to render().

export type TemplateResult<T extends ResultType = ResultType> =
  UncompiledTemplateResult<T>;

export type UncompiledTemplateResult<T extends ResultType = ResultType> = {
  ['_$litType$']: T;
  strings: TemplateStringsArray;
  values: unknown[];
};

Specializations

Type	Tag
HTMLTemplateResult	html
SVGTemplateResult	svg
MathMLTemplateResult	mathml

CompiledTemplateResult

A TemplateResult that has been pre-processed by @lit-labs/compiler, skipping the template preparation step at runtime.

export interface CompiledTemplateResult {
  ['_$litType$']: CompiledTemplate;
  values: unknown[];
}

Part types

Parts represent dynamic binding sites within a rendered template. Each binding expression in a template corresponds to one part.

export type Part =
  | ChildPart
  | AttributePart
  | PropertyPart
  | BooleanAttributePart
  | ElementPart
  | EventPart;

ChildPart

Represents a binding in child node position — the content between two elements or inside text content.

class ChildPart {
  readonly type: 2; // CHILD_PART
  readonly options: RenderOptions | undefined;

  get parentNode(): Node;
  get startNode(): Node | null;
  get endNode(): Node | null;

  // For RootParts only:
  setConnected(isConnected: boolean): void;
}

Template syntax: ${value}

AttributePart

Represents a binding in an HTML attribute value position.

class AttributePart {
  readonly type: 1; // ATTRIBUTE_PART
  readonly element: HTMLElement;
  readonly name: string;
  readonly options: RenderOptions | undefined;
  readonly strings?: ReadonlyArray<string>;
}

Template syntax: attr="${value}" or attr="prefix-${value}-suffix"

PropertyPart

Extends AttributePart. Sets a DOM property on the element instead of an attribute.

class PropertyPart extends AttributePart {
  override readonly type: 3; // PROPERTY_PART
}

Template syntax: .propName="${value}"

BooleanAttributePart

Extends AttributePart. Toggles an attribute using toggleAttribute based on the truthiness of the value. When the value is falsy or nothing, the attribute is removed.

class BooleanAttributePart extends AttributePart {
  override readonly type: 4; // BOOLEAN_ATTRIBUTE_PART
}

Template syntax: ?attr="${boolValue}"

EventPart

Extends AttributePart. Manages an event listener via addEventListener / removeEventListener. Accepts a function or an EventListenerObject. Event options (capture, once, passive) are taken from the listener object.

class EventPart extends AttributePart {
  override readonly type: 5; // EVENT_PART
}

Template syntax: @eventname="${handler}"

ElementPart

Represents a binding on an element itself (used by element directives like ref).

class ElementPart {
  readonly type: 6; // ELEMENT_PART
  readonly element: Element;
  readonly options: RenderOptions | undefined;
}

Template syntax: ${directive(element)}

RootPart

A ChildPart returned from a top-level render() call. Adds a setConnected method for managing AsyncDirective connection state across the entire rendered tree.

export interface RootPart extends ChildPart {
  setConnected(isConnected: boolean): void;
}

Directives

Directive

Base class for creating custom directives. Subclass Directive, implement render(), and wrap it with directive().

export abstract class Directive {
  constructor(_partInfo: PartInfo) {}

  abstract render(...props: Array<unknown>): unknown;

  update(_part: Part, props: Array<unknown>): unknown;
}

directive(c)

Creates a user-facing directive function from a Directive class. The returned function has the same parameters as the directive’s render() method.

export const directive: <C extends DirectiveClass>(c: C) =>
  (...values: DirectiveParameters<InstanceType<C>>) => DirectiveResult<C>

import { Directive, directive } from 'lit/directive.js';

class MyDirective extends Directive {
  render(value: string) {
    return value.toUpperCase();
  }
}

const myDirective = directive(MyDirective);

// Usage in a template:
html`${myDirective('hello')}`; // renders "HELLO"

DirectiveResult<C>

The object returned by a directive factory function. It captures the directive class and its argument values without evaluating the directive.

export interface DirectiveResult<C extends DirectiveClass = DirectiveClass> {
  ['_$litDirective$']: C;
  values: DirectiveParameters<InstanceType<C>>;
}

PartInfo

Information about the part a directive is bound to. Passed to the Directive constructor.

export type PartInfo = ChildPartInfo | AttributePartInfo | ElementPartInfo;

ChildPartInfo · { type: 2 }

Directive is bound in child position.

AttributePartInfo · { type: 1 | 3 | 4 | 5; name: string; tagName: string; strings?: ReadonlyArray<string> }

Directive is bound in attribute, property, boolean attribute, or event position.

ElementPartInfo · { type: 6 }

Directive is bound to an element.

PartType

Numeric constants identifying each part type.

export const PartType = {
  ATTRIBUTE: 1,
  CHILD: 2,
  PROPERTY: 3,
  BOOLEAN_ATTRIBUTE: 4,
  EVENT: 5,
  ELEMENT: 6,
} as const;

Security

SanitizerFactory

A factory that creates sanitizer functions for DOM writes. Used to implement Content Security Policy enforcement.

export type SanitizerFactory = (
  node: Node,
  name: string,
  type: 'property' | 'attribute'
) => ValueSanitizer;

ValueSanitizer

A function that sanitizes a value before it is written to the DOM.

export type ValueSanitizer = (value: unknown) => unknown;

Set a custom sanitizer via render.setSanitizer(factory) (available when security hooks are enabled).