Helpers for working with component templates.

The ShadowTemplateMixin lets you define a component template that will be used to popuplate the shadow subtree of new component instances. These helpers, especially the html function, are intended to simplify the creation of such templates.

In particular, these helpers can be useful in patching templates inherited from a base class.

Some of these functions take descriptors that can either be a class, a tag name, or an HTML template. These are generally used to fill specific roles in an element's template; see element roles.


createElement(descriptor) static method

Create an element from a role descriptor (a component class constructor, an HTML tag name, or an HTML template).

If the descriptor is an HTML template, and the resulting document fragment contains a single top-level node, that node is returned directly (instead of the fragment).

  • descriptor: function|string|HTMLTemplateElementthe descriptor that will be used to create the element

Returns: Node the new element

findAndReplace(template, selector, descriptor) static method

Perform a find-and-replace of all elements in a template that match a given CSS selector, replacing them with elements instantiated from the given descriptor.

The descriptor used for the replacements can be a 1) component class constructor, 2) an HTML tag name, or 3) an HTML template. For #1 and #2, if the existing elements that match the selector are already of the desired class/tag name, the replacement operation is skipped.

  • template: HTMLTemplateElement|Elementthe template to search
  • selector: stringthe CSS selector used for the search
  • descriptor: function|string|HTMLTemplateElementthe descriptor used to generate replacement elements

html(strings, substitutions) static method

A JavaScript template string literal that returns an HTML template.


const myTemplate = html`Hello, <em>world</em>.`

returns an HTMLTemplateElement whose innerHTML is Hello, <em>world</em>.

This function is called html so that it can be easily used with HTML syntax-highlighting extensions for various popular code editors.

  • strings: TemplateStringsArraythe strings passed to the JavaScript template literal
  • substitutions: Array.the variable values passed to the JavaScript template literal

Returns: HTMLTemplateElement

replace(original, replacement) static method

Replace an original node in a tree or document fragment with the indicated replacement node or template. The attributes and children of the original node will be moved to the replacement.

  • original: Node|nullan existing node to be replaced
  • replacement: Nodethe node to replace the existing node with

wrap(original, wrapper, destination) static method

Destructively wrap a node or document fragment with the indicated wrapper node. The contents of the original node/fragment are moved to the indicated destination node (which should be a node within the wrapper).

  • original: Nodethe node to wrap
  • wrapper: DocumentFragment|Elementthe node to wrap with
  • destination: stringa CSS selector indicated a node in the wrapper in which the original node should be put