Module to add shady DOM/shady CSS polyfill support to lit-html template rendering. See the render method for details.
Interprets a template literal as an HTML template that can efficiently render to and update a container.
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.
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
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
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.
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
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
Usage considerations when using shimmed custom properties or
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,
should be called in the element's
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.
@apply mixing css shorthand property names with
non-shorthand names (for example
border-width) is not
Template factory which scopes template DOM using ShadyCSS.
Interprets a template literal as an SVG template that can efficiently render to and update a container.
Generated using TypeDoc