• Public
  • Public/Protected
  • All

External module lit-html

Main lit-html module.

Main exports:


Type aliases


DirectiveFactory: function

Type declaration

    • (...args: any[]): object
    • Parameters

      • Rest ...args: any[]

      Returns object


DirectiveFn: function

Type declaration

    • (part: Part): void
    • Parameters

      Returns void


Primitive: null | undefined | boolean | number | string | Symbol | bigint


TemplateFactory: function

A function type that creates a Template from a TemplateResult.

This is a hook into the template-creation process for rendering that requires some modification of templates before they're used, like ShadyCSS, which must add classes to elements and remove styles.

Templates should be cached as aggressively as possible, so that many TemplateResults produced from the same expression only do the work of creating the Template the first time.

Templates are usually cached by TemplateResult.strings and TemplateResult.type, but may be cached by other keys if this function modifies the template.

Note that currently TemplateFactories must not add, remove, or reorder expressions, because there is no way to describe such a modification to render() so that values are interpolated to the correct place in the template instances.

Type declaration


TemplatePart: object | object

A placeholder for a dynamic expression in an HTML template.

There are two built-in part types: AttributePart and NodePart. NodeParts always represent a single dynamic expression, while AttributeParts may represent as many expressions are contained in the attribute.

A Template's parts are mutable, so parts can be replaced or modified (possibly to implement different template semantics). The contract is that parts can only be replaced, not removed, added or reordered, and parts must always consume the correct number of values in their update() method.

TODO(justinfagnani): That requirement is a little fragile. A TemplateInstance could instead be more careful about which values it gives to Part.update().


templateCache: object

The first argument to JS template tags retain identity across multiple calls to a tag for the same literal, so we can cache work done per literal in a Map.

Safari currently has a bug which occasionally breaks this behaviour, so we need to cache the Template at two levels. We first cache the TemplateStringsArray, and if that fails, we cache a key constructed by joining the strings array.

Type declaration


Const boundAttributeSuffix

boundAttributeSuffix: "$lit$" = "$lit$"

Suffix appended to all bound attribute names.

Const defaultTemplateProcessor

defaultTemplateProcessor: DefaultTemplateProcessor = new DefaultTemplateProcessor()

Const isCEPolyfill

isCEPolyfill: boolean = window.customElements !== undefined &&(window.customElements as MaybePolyfilledCe).polyfillWrapFlushCallback !==undefined

True if the custom elements polyfill is in use.

Const lastAttributeNameRegex

lastAttributeNameRegex: RegExp = /([ \x09\x0a\x0c\x0d])([^\0-\x1F\x7F-\x9F \x09\x0a\x0c\x0d"'>=/]+)([ \x09\x0a\x0c\x0d]*=[ \x09\x0a\x0c\x0d]*(?:[^ \x09\x0a\x0c\x0d"'`<>=]*|"[^"]*|'[^']*))$/

This regex extracts the attribute name preceding an attribute-position expression. It does this by matching the syntax allowed for attributes against the string literal directly preceding the expression, assuming that the expression is in an attribute-value position.

See attributes in the HTML spec: https://www.w3.org/TR/html5/syntax.html#attributes-0

"\0-\x1F\x7F-\x9F" are Unicode control characters

" \x09\x0a\x0c\x0d" are HTML space characters: https://www.w3.org/TR/html5/infrastructure.html#space-character

So an attribute is:

  • The name: any character except a control character, space character, ('), ("), ">", "=", or "/"
  • Followed by zero or more space characters
  • Followed by "="
  • Followed by zero or more space characters
  • Followed by:
    • Any character except space, ('), ("), "<", ">", "=", (`), or
    • (") then any non-("), or
    • (') then any non-(')

Const marker

marker: string = `{{lit-${String(Math.random()).slice(2)}}}`

An expression marker with embedded unique key to avoid collision with possible text in templates.

Const markerRegex

markerRegex: RegExp = new RegExp(`${marker}|${nodeMarker}`)

Const noChange

noChange: object

A sentinel value that signals that a value was handled by a directive and should not be written to the DOM.

Const nodeMarker

nodeMarker: string = `<!--${marker}-->`

An expression marker used text-positions, multi-binding attributes, and attributes with markup-like text values.

Const nothing

nothing: object

A sentinel value that signals a NodePart to fully clear its content.

Type declaration

Const parts

parts: WeakMap<Node, NodePart> = new WeakMap<Node, NodePart>()

Const templateCaches

templateCaches: Map<string, object> = new Map<string, templateCache>()


Const createMarker

  • createMarker(): Comment
  • Returns Comment

Const directive

  • directive<F>(f: F): F
  • Brands a function as a directive factory function so that lit-html will call the function during template rendering, rather than passing as a value.

    A directive is a function that takes a Part as an argument. It has the signature: (part: Part) => void.

    A directive factory is a function that takes arguments for data and configuration and returns a directive. Users of directive usually refer to the directive factory as the directive. For example, "The repeat directive".

    Usually a template author will invoke a directive factory in their template with relevant arguments, which will then return a directive function.

    Here's an example of using the repeat() directive factory that takes an array and a function to render an item:

    html`<ul><${repeat(items, (item) => html`<li>${item}</li>`)}</ul>`

    When repeat is invoked, it returns a directive function that closes over items and the template function. When the outer template is rendered, the return directive function is called with the Part for the expression. repeat then performs it's custom logic to render multiple items.

    Type parameters


    • f: F

      The directive factory function. Must be a function that returns a function of the signature (part: Part) => void. The returned function will be called with the part object.

    Returns F

Const html

  • html(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult
  • Interprets a template literal as an HTML template that can efficiently render to and update a container.


    • strings: TemplateStringsArray
    • Rest ...values: unknown[]

    Returns TemplateResult

Const isDirective

  • isDirective(o: unknown): boolean
  • Parameters

    • o: unknown

    Returns boolean

Const isIterable

  • isIterable(value: unknown): boolean
  • Parameters

    • value: unknown

    Returns boolean

Const isPrimitive

  • isPrimitive(value: unknown): boolean
  • Parameters

    • value: unknown

    Returns boolean

Const isTemplatePartActive

  • Parameters

    Returns boolean

Const removeNodes

  • removeNodes(container: Node, start: Node | null, end?: Node | null): void
  • Removes nodes, starting from start (inclusive) to end (exclusive), from container.


    • container: Node
    • start: Node | null
    • Default value end: Node | null = null

    Returns void

Const render

  • Renders a template to a container.

    To update a container with new values, reevaluate the template literal and call render with the new result.


    • result: TemplateResult

      a TemplateResult created by evaluating a template tag like html or svg.

    • container: Element | DocumentFragment

      A DOM parent to render to. The entire contents are either replaced, or efficiently updated if the same result type was previous rendered there.

    • Optional options: Partial<RenderOptions>

      RenderOptions for the entire render tree rendered to this container. Render options must not change between renders to the same container, as those changes will not effect previously rendered DOM.

    Returns void

Const reparentNodes

  • reparentNodes(container: Node, start: Node | null, end?: Node | null, before?: Node | null): void
  • Reparents nodes, starting from start (inclusive) to end (exclusive), into another container (could be the same container), before before. If before is null, it appends the nodes to the container.


    • container: Node
    • start: Node | null
    • Default value end: Node | null = null
    • Default value before: Node | null = null

    Returns void

Const svg

  • Interprets a template literal as an SVG template that can efficiently render to and update a container.


    • strings: TemplateStringsArray
    • Rest ...values: unknown[]

    Returns SVGTemplateResult


  • The default TemplateFactory which caches Templates keyed on result.type and result.strings.


    Returns Template

Generated using TypeDoc