• Public
  • Public/Protected
  • All

Main lit-html module.

Main exports:


Type aliases


DirectiveFn: function

Type declaration

    • (part: Part): void
    • Parameters

      Returns void


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 any).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.

Type declaration

Const nodeMarker

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

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

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 so that lit-html will call the function during template rendering, rather than passing as a value.

    Type parameters

    • F: Function


    • 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: any[]): TemplateResult
  • Interprets a template literal as an HTML template that can efficiently render to and update a container.


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

    Returns TemplateResult

Const isDirective

  • isDirective(o: any): boolean
  • Parameters

    • o: any

    Returns boolean

Const isPrimitive

  • isPrimitive(value: any): boolean
  • Parameters

    • value: any

    Returns boolean

Const isTemplatePartActive

  • Parameters

    Returns boolean

Const removeNodes

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


    • container: Node
    • startNode: Node | null
    • Default value endNode: 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 startNode (inclusive) to endNode (exclusive), into another container (could be the same container), before beforeNode. If beforeNode 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: any[]

    Returns SVGTemplateResult


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


    Returns Template


  • Module
  • Object literal
  • Variable
  • Function
  • Function with type parameter
  • Index signature
  • Type alias
  • Enumeration
  • Enumeration member
  • Property
  • Method
  • Interface
  • Interface with type parameter
  • Constructor
  • Property
  • Method
  • Index signature
  • Class
  • Class with type parameter
  • Constructor
  • Property
  • Method
  • Accessor
  • Index signature
  • Inherited constructor
  • Inherited property
  • Inherited method
  • Inherited accessor
  • Protected property
  • Protected method
  • Protected accessor
  • Private property
  • Private method
  • Private accessor
  • Static property
  • Static method

Generated using TypeDoc