• Version 2.0.1
  • Published
  • 917 kB
  • 1 dependency
  • BSD-3-Clause license


npm i lit-html
yarn add lit-html
pnpm add lit-html


HTML templates literals in JavaScript



variable HTML_RESULT

const HTML_RESULT: number;
  • TemplateResult types

variable noChange

const noChange: Symbol;
  • A sentinel value that signals that a value was handled by a directive and should not be written to the DOM.

variable nothing

const nothing: Symbol;
  • A sentinel value that signals a ChildPart to fully clear its content.

    const button = html`${
    ? html`<button>DELETE</button>`
    : nothing

    Prefer using nothing over other falsy values as it provides a consistent behavior between various expression binding contexts.

    In child expressions, undefined, null, '', and nothing all behave the same and render no nodes. In attribute expressions, nothing _removes_ the attribute, while undefined and null will render an empty string. In property expressions nothing becomes undefined.

variable render

const render: {
value: unknown,
container: HTMLElement | DocumentFragment,
options?: RenderOptions | undefined
): RootPart;
setSanitizer: (newSanitizer: SanitizerFactory) => void;
createSanitizer: SanitizerFactory;
_testOnlyClearSanitizerFactoryDoNotCallOrElse: () => void;
  • Renders a value, usually a lit-html TemplateResult, to the container.

    Parameter value

    Parameter container

    Parameter options

variable SVG_RESULT

const SVG_RESULT: number;


    function html

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

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

      The html tag returns a description of the DOM to render as a value. It is lazy, meaning no work is done until the template is rendered. When rendering, if a template comes from the same expression as a previously rendered result, it's efficiently updated instead of replaced.

    function resolveDirective

    resolveDirective: (
    part: ChildPart | AttributePart | ElementPart,
    value: unknown,
    parent?: DirectiveParent,
    attributeIndex?: number
    ) => unknown;

      function svg

      svg: (strings: TemplateStringsArray, ...values: unknown[]) => TemplateResult<2>;
      • Interprets a template literal as an SVG template that can efficiently render to and update a container.


      class AttributePart

      class AttributePart implements Disconnectable {}


        element: HTMLElement,
        name: string,
        strings: readonly string[],
        parent: Disconnectable,
        options: RenderOptions

          property element

          readonly element: HTMLElement;

            property name

            readonly name: string;

              property options

              readonly options: RenderOptions;

                property strings

                readonly strings?: readonly string[];
                • If this attribute part represents an interpolation, this contains the static strings of the interpolation. For single-value, complete bindings, this is undefined.

                property tagName

                readonly tagName: string;

                  property type

                  readonly type: 1 | 3 | 4 | 5;

                    class BooleanAttributePart

                    class BooleanAttributePart extends AttributePart {}

                      property type

                      readonly type: number;

                        class ChildPart

                        class ChildPart implements Disconnectable {}


                          startNode: ChildNode,
                          endNode: ChildNode,
                          parent: TemplateInstance | ChildPart,
                          options: RenderOptions

                            property endNode

                            readonly endNode: Node;
                            • The part's trailing marker node, if any. See .parentNode for more information.

                            property options

                            readonly options: RenderOptions;

                              property parentNode

                              readonly parentNode: Node;
                              • The parent node into which the part renders its content.

                                A ChildPart's content consists of a range of adjacent child nodes of .parentNode, possibly bordered by 'marker nodes' (.startNode and .endNode).

                                - If both .startNode and .endNode are non-null, then the part's content consists of all siblings between .startNode and .endNode, exclusively.

                                - If .startNode is non-null but .endNode is null, then the part's content consists of all siblings following .startNode, up to and including the last child of .parentNode. If .endNode is non-null, then .startNode will always be non-null.

                                - If both .endNode and .startNode are null, then the part's content consists of all child nodes of .parentNode.

                              property startNode

                              readonly startNode: Node;
                              • The part's leading marker node, if any. See .parentNode for more information.

                              property type

                              readonly type: number;

                                class ElementPart

                                class ElementPart implements Disconnectable {}


                                  constructor(element: Element, parent: Disconnectable, options: RenderOptions);

                                    property element

                                    element: Element;

                                      property options

                                      options: RenderOptions;

                                        property type

                                        readonly type: number;

                                          class EventPart

                                          class EventPart extends AttributePart {}


                                            element: HTMLElement,
                                            name: string,
                                            strings: readonly string[],
                                            parent: Disconnectable,
                                            options: RenderOptions

                                              property type

                                              readonly type: number;

                                                method handleEvent

                                                handleEvent: (event: Event) => void;

                                                  class PropertyPart

                                                  class PropertyPart extends AttributePart {}

                                                    property type

                                                    readonly type: number;


                                                      interface CompiledTemplate

                                                      interface CompiledTemplate extends Omit<Template, 'el'> {}

                                                        property el

                                                        el?: HTMLTemplateElement;

                                                          property h

                                                          h: TrustedHTML;

                                                            interface CompiledTemplateResult

                                                            interface CompiledTemplateResult {}

                                                              property ['_$litType$']

                                                              ['_$litType$']: CompiledTemplate;

                                                                property values

                                                                values: unknown[];

                                                                  interface DirectiveParent

                                                                  interface DirectiveParent {}

                                                                    interface Disconnectable

                                                                    interface Disconnectable {}

                                                                      interface RenderOptions

                                                                      interface RenderOptions {}
                                                                      • Object specifying options for controlling lit-html rendering. Note that while render may be called multiple times on the same container (and renderBefore reference node) to efficiently update the rendered content, only the options passed in during the first render are respected during the lifetime of renders to that unique container + renderBefore combination.

                                                                      property creationScope

                                                                      creationScope?: {
                                                                      importNode(node: Node, deep?: boolean): Node;
                                                                      • Node used for cloning the template (importNode will be called on this node). This controls the ownerDocument of the rendered DOM, along with any inherited context. Defaults to the global document.

                                                                      property host

                                                                      host?: object;
                                                                      • An object to use as the this value for event listeners. It's often useful to set this to the host component rendering a template.

                                                                      property isConnected

                                                                      isConnected?: boolean;
                                                                      • The initial connected state for the top-level part being rendered. If no isConnected option is set, AsyncDirectives will be connected by default. Set to false if the initial render occurs in a disconnected tree and AsyncDirectives should see isConnected === false for their initial render. The part.setConnected() method must be used subsequent to initial render to change the connected state of the part.

                                                                      property renderBefore

                                                                      renderBefore?: ChildNode | null;
                                                                      • A DOM node before which to render content in the container.

                                                                      interface RootPart

                                                                      interface RootPart extends ChildPart {}
                                                                      • A top-level ChildPart returned from render that manages the connected state of AsyncDirectives created throughout the tree below it.

                                                                      method setConnected

                                                                      setConnected: (isConnected: boolean) => void;
                                                                      • Sets the connection state for AsyncDirectives contained within this root ChildPart.

                                                                        lit-html does not automatically monitor the connectedness of DOM rendered; as such, it is the responsibility of the caller to render to ensure that part.setConnected(false) is called before the part object is potentially discarded, to ensure that AsyncDirectives have a chance to dispose of any resources being held. If a RootPart that was prevously disconnected is subsequently re-connected (and its AsyncDirectives should re-connect), setConnected(true) should be called.

                                                                        Parameter isConnected

                                                                        Whether directives within this tree should be connected or not

                                                                      Type Aliases

                                                                      type HTMLTemplateResult

                                                                      type HTMLTemplateResult = TemplateResult<typeof HTML_RESULT>;

                                                                        type Part

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

                                                                          type SanitizerFactory

                                                                          type SanitizerFactory = (
                                                                          node: Node,
                                                                          name: string,
                                                                          type: 'property' | 'attribute'
                                                                          ) => ValueSanitizer;
                                                                          • Used to sanitize any value before it is written into the DOM. This can be used to implement a security policy of allowed and disallowed values in order to prevent XSS attacks.

                                                                            One way of using this callback would be to check attributes and properties against a list of high risk fields, and require that values written to such fields be instances of a class which is safe by construction. Closure's Safe HTML Types is one implementation of this technique ( The TrustedTypes polyfill in API-only mode could also be used as a basis for this technique (

                                                                            Parameter node

                                                                            The HTML node (usually either a #text node or an Element) that is being written to. Note that this is just an exemplar node, the write may take place against another instance of the same class of node.

                                                                            Parameter name

                                                                            The name of an attribute or property (for example, 'href').

                                                                            Parameter type

                                                                            Indicates whether the write that's about to be performed will be to a property or a node. A function that will sanitize this class of writes.

                                                                          type SVGTemplateResult

                                                                          type SVGTemplateResult = TemplateResult<typeof SVG_RESULT>;

                                                                            type TemplateResult

                                                                            type TemplateResult<T extends ResultType = ResultType> = {
                                                                            ['_$litType$']: T;
                                                                            strings: TemplateStringsArray;
                                                                            values: unknown[];
                                                                            • The return type of the template tag functions.

                                                                            type ValueSanitizer

                                                                            type ValueSanitizer = (value: unknown) => unknown;
                                                                            • A function which can sanitize values that will be written to a specific kind of DOM sink.

                                                                              See SanitizerFactory.

                                                                              Parameter value

                                                                              The value to sanitize. Will be the actual value passed into the lit-html template literal, so this could be of any type. The value to write to the DOM. Usually the same as the input value, unless sanitization is needed.

                                                                            Package Files (1)

                                                                            Dependencies (1)

                                                                            Dev Dependencies (13)

                                                                            Peer Dependencies (0)

                                                                            No peer dependencies.


                                                                            To add a badge like this badgeto your package's README, use the codes available below.

                                                                            You may also use to create a custom badge linking to

                                                                            • Markdown
                                                                            • HTML
                                                                              <a href=""><img src="" alt=""></a>