• Public
  • Public/Protected
  • All

External module shady-render

Module to add shady DOM/shady CSS polyfill support to lit-html template rendering. See the render method for details.




  • insertNodeIntoTemplate(template: Template, node: Node, refNode?: Node | null): void
  • Inserts the given node into the Template, optionally before the given refNode. In addition to inserting the node into the Template, the Template part indices are updated to match the mutated Template DOM.


    • template: Template
    • node: Node
    • Default value refNode: Node | null = null

    Returns void


  • removeNodesFromTemplate(template: Template, nodesToRemove: Set<Node>): void
  • Removes the list of nodes from a Template safely. In addition to removing nodes from the Template, the Template part indices are updated to match the mutated Template DOM.

    As the template is walked the removal state is tracked and part indices are adjusted as needed.

    div div#1 (remove) <-- start removing (removing node is div#1) div div#2 (remove) <-- continue removing (removing node is still div#1) div div <-- stop removing since previous sibling is the removing node (div#1, removed 4 nodes)


    • template: Template
    • nodesToRemove: Set<Node>

    Returns void

Const render

  • Extension to the standard render method which supports rendering to ShadowRoots when the ShadyDOM (https://github.com/webcomponents/shadydom) and ShadyCSS (https://github.com/webcomponents/shadycss) polyfills are used or when the webcomponentsjs (https://github.com/webcomponents/webcomponentsjs) polyfill is used.

    Adds a scopeName option which is used to scope element DOM and stylesheets when native ShadowDOM is unavailable. The scopeName will be added to the class attribute of all rendered DOM. In addition, any style elements will be automatically re-written with this scopeName selector and moved out of the rendered DOM and into the document <head>.

    It is common to use this render method in conjunction with a custom element which renders a shadowRoot. When this is done, typically the element's localName should be used as the scopeName.

    In addition to DOM scoping, ShadyCSS also supports a basic shim for css custom properties (needed only on older browsers like IE11) and a shim for a deprecated feature called @apply that supports applying a set of css custom properties to a given location.

    Usage considerations:

    • Part values in <style> elements are only applied the first time a given scopeName renders. Subsequent changes to parts in style elements will have no effect. Because of this, parts in style elements should only be used for values that will never change, for example parts that set scope-wide theme values or parts which render shared style elements.

    • Note, due to a limitation of the ShadyDOM polyfill, rendering in a custom element's constructor is not supported. Instead rendering should either done asynchronously, for example at microtask timing (for example Promise.resolve()), or be deferred until the first time the element's connectedCallback runs.

    Usage considerations when using shimmed custom properties or @apply:

    • Whenever any dynamic changes are made which affect css custom properties, ShadyCSS.styleElement(element) must be called to update the element. There are two cases when this is needed: (1) the element is connected to a new parent, (2) a class is added to the element that causes it to match different custom properties. To address the first case when rendering a custom element, styleElement should be called in the element's connectedCallback.

    • Shimmed custom properties may only be defined either for an entire shadowRoot (for example, in a :host rule) or via a rule that directly matches an element with a shadowRoot. In other words, instead of flowing from parent to child as do native css custom properties, shimmed custom properties flow only from shadowRoots to nested shadowRoots.

    • When using @apply mixing css shorthand property names with non-shorthand names (for example border and border-width) is not supported.


    Returns void

Generated using TypeDoc