lit-html

Variables

• ATTRIBUTE_PART
• BOOLEAN_ATTRIBUTE_PART
• CHILD_PART
• COMMENT_PART
• ELEMENT_PART
• EVENT_PART
• HTML_RESULT
• MATHML_RESULT
• noChange
• nothing
• PROPERTY_PART
• render
• SVG_RESULT

Functions

• html()
• mathml()
• resolveDirective()
• svg()

Classes

• AttributePart

  • element
  • name
  • options
  • strings
  • tagName
  • type
• BooleanAttributePart

  • type
• ChildPart

  • endNode
  • options
  • parentNode
  • startNode
  • type
• ElementPart

  • element
  • options
  • type
• EventPart

  • handleEvent()
  • type
• PropertyPart

  • type
• TemplateInstance

  • parentNode

Interfaces

• CompiledTemplate

  • el
  • h
• CompiledTemplateResult

  • ['_$litType$']
  • values
• DirectiveParent
• Disconnectable
• RenderOptions

  • creationScope
  • host
  • isConnected
  • renderBefore
• RootPart

  • setConnected()

Type Aliases

• HTMLTemplateResult
• MathMLTemplateResult
• MaybeCompiledTemplateResult
• Part
• SanitizerFactory
• SVGTemplateResult
• TemplateResult
• UncompiledTemplateResult
• ValueSanitizer

Namespaces

• LitUnstable
• LitUnstable.DebugLog

  • BeginRender
  • CommitAttribute
  • CommitBooleanAttribute
  • CommitEventListener
  • CommitNode
  • CommitNothingToChildEntry
  • CommitPartEntry
  • CommitProperty
  • CommitText
  • CommitToElementBinding
  • EndRender
  • Entry
  • SetPartValue
  • TemplateInstantiated
  • TemplateInstantiatedAndUpdated
  • TemplatePrep
  • TemplateUpdating

variable ATTRIBUTE_PART

const ATTRIBUTE_PART: number;

variable BOOLEAN_ATTRIBUTE_PART

const BOOLEAN_ATTRIBUTE_PART: number;

variable CHILD_PART

const CHILD_PART: number;

variable COMMENT_PART

const COMMENT_PART: number;

variable ELEMENT_PART

const ELEMENT_PART: number;

variable EVENT_PART

const EVENT_PART: number;

variable HTML_RESULT

const HTML_RESULT: number;

• TemplateResult types

variable MATHML_RESULT

const MATHML_RESULT: number;

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`${
   user.isAdmin
     ? 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 PROPERTY_PART

const PROPERTY_PART: number;

variable render

const render: {
    (
        value: unknown,
        container: HTMLElement | DocumentFragment,
        options?: RenderOptions
    ): RootPart;
    setSanitizer: (newSanitizer: SanitizerFactory) => void;
    createSanitizer: SanitizerFactory;
    _testOnlyClearSanitizerFactoryDoNotCallOrElse: () => void;
};

• Renders a value, usually a lit-html TemplateResult, to the container.

  This example renders the text "Hello, Zoe!" inside a paragraph tag, appending it to the container document.body.

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

  Parameter value

  Any [renderable value](https://lit.dev/docs/templates/expressions/#child-expressions), typically a created by evaluating a template tag like or .

  Parameter container

  A DOM container to render to. The first render will append the rendered value to the container, and subsequent renders will efficiently update the rendered value if the same result type was previously rendered there.

  Parameter options

  See for options documentation.

  See Also

  • Rendering Lit HTML Templates

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 mathml

mathml: (
    strings: TemplateStringsArray,
    ...values: unknown[]
) => TemplateResult<3>;

• Interprets a template literal as MathML fragment that can efficiently render to and update a container.

  const num = mathml`<mn>1</mn>`;
  
  const eq = html`
    <math>
      ${num}
    </math>`;

  The mathml *tag function* should only be used for MathML fragments, or elements that would be contained **inside** a <math> HTML element. A common error is placing a <math> *element* in a template tagged with the mathml tag function. The <math> element is an HTML element and should be used within a template tagged with the tag function.

  In LitElement usage, it's invalid to return an MathML fragment from the render() method, as the MathML fragment will be contained within the element's shadow root and thus not be properly contained within a <math> HTML element.

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 fragment that can efficiently render to and update a container.

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

  The svg *tag function* should only be used for SVG fragments, or elements that would be contained **inside** an <svg> HTML element. A common error is placing an <svg> *element* in a template tagged with the svg tag function. The <svg> element is an HTML element and should be used within a template tagged with the tag function.

  In LitElement usage, it's invalid to return an SVG fragment from the render() method, as the SVG fragment will be contained within the element's shadow root and thus not be properly contained within an <svg> HTML element.

type HTMLTemplateResult

type HTMLTemplateResult = TemplateResult<typeof HTML_RESULT>;

type MathMLTemplateResult

type MathMLTemplateResult = TemplateResult<typeof MATHML_RESULT>;

type MaybeCompiledTemplateResult

type MaybeCompiledTemplateResult<T extends ResultType = ResultType> =
    | UncompiledTemplateResult<T>
    | CompiledTemplateResult;

• This is a template result that may be either uncompiled or compiled.

  In the future, TemplateResult will be this type. If you want to explicitly note that a template result is potentially compiled, you can reference this type and it will continue to behave the same through the next major version of Lit. This can be useful for code that wants to prepare for the next major version of Lit.

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 ( https://github.com/google/safe-html-types/blob/master/doc/safehtml-types.md). The TrustedTypes polyfill in API-only mode could also be used as a basis for this technique (https://github.com/WICG/trusted-types).

  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> = UncompiledTemplateResult<T>;

• The return type of the template tag functions, and .

  A TemplateResult object holds all the information about a template expression required to render it: the template strings, expression values, and type of template (html or svg).

  TemplateResult objects do not create any DOM on their own. To create or update DOM you need to render the TemplateResult. See [Rendering](https://lit.dev/docs/components/rendering) for more information.

  In Lit 4, this type will be an alias of MaybeCompiledTemplateResult, so that code will get type errors if it assumes that Lit templates are not compiled. When deliberately working with only one, use either or explicitly.

type UncompiledTemplateResult

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

• The return type of the template tag functions, and when it hasn't been compiled by @lit-labs/compiler.

  A TemplateResult object holds all the information about a template expression required to render it: the template strings, expression values, and type of template (html or svg).

  TemplateResult objects do not create any DOM on their own. To create or update DOM you need to render the TemplateResult. See [Rendering](https://lit.dev/docs/components/rendering) for more information.

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.