Light DOMLWC

Shadow DOM lets you place the children in a scoped subtree, so document-level CSS can't restyle the button by accident, for example. This subtree is called a shadow tree.

There is one case where a style rule inside a shadow tree matches an element outside the shadow tree. You can define styles for the host element, using the :host pseudoclass or the :host() functional pseudoclass.

Because shadow DOM is not available on all platforms, Polymer takes advantage of the shady DOM and shady CSS polyfills if they're installed. These polyfills are included in the webcomponents-lite.js polyfill bundle.

The ordering may be a little confusing at first. At each level, the light DOM children are assigned to a slot in the host's shadow DOM. The span "I'm in light DOM" is assigned to the slot #parent-slot in 's shadow DOM. The #parent-slot is then assigned to #child-slot in 's shadow DOM.

Light DOMslots

The Polymer.FlattenedNodesObserver class provides utilities to track an element's flattened tree. That is, a list of the node's child nodes, with any elements replaced by their distributed nodes. FlattenedNodesObserver is an optional utility that can be loaded from lib/utils/flattened-nodes-observer.html.

You're viewing an older version of the Polymer library documentation. Please see Polymer 3.0 for the latest.

The callback argument lists added and removed nodes, not just elements. If you're only interested in elements, you can filter the node list:

To emulate shadow DOM's rendering of the flattened tree, the shady DOM polyfill has to maintain virtual children and shadowRoot properties with separate logical trees. Each host element's actual children—the descendant tree visible to the browser—is a pre-flattened tree of shadow and light DOM children. The tree you'll see using developer tools looks like the rendered tree, not the logical tree.

Light dommeaning

Under the polyfill, the slot elements don't appear in the browser's view of the tree. So unlike native shadow DOM, slots don't take part in event bubbling.

Read more on Web Fundamentals. This document gives an overview of shadow DOM as it relates to Polymer. For a more comprehensive overview of Shadow DOM, see Shadow DOM v1: self-contained web components on Web Fundamentals.

By default, if an element has shadow DOM, the shadow tree is rendered instead of the element's children. To allow children to render, you can add a element to your shadow tree. Think of the as a placeholder showing where child nodes will render. Consider the following shadow tree for :

To let users customize your element, you can expose specific styling properties using CSS custom properties and custom property mixins. Custom properties provide a way to add a styling API to your element.

The Shady CSS polyfill emulates shadow DOM style encapsulation, and also provides emulation for CSS custom properties and custom property mixins.

Shadow DOM is a new DOM feature that helps you build components. You can think of shadow DOM as a scoped subtree inside your element.

You can't directly style anything in a shadow tree using a CSS rule outside of the shadow tree. The exception is CSS properties (such as color and font) that inherit down the tree. A shadow tree inherits CSS properties from its host.

By default, custom events don't propagate though shadow DOM boundaries. To allow a custom event to travel through a shadow DOM boundary and be retargeted, you need to create it with the composed flag set to true:

For more information on events in shadow trees, see The Shadow DOM event model in the Web Fundamentals article on shadow DOM.

You can also style light DOM children that are assigned to slots using the ::slotted() pseudoelement. For example, ::slotted(img) selects any image tags that are assigned to slots in the shadow tree.

You pass the FlattenedNodesObserver a callback to be invoked when nodes are added or removed. The callback takes a single Object argument, with addedNodes and removedNodes arrays.

Litlight DOM

The has two top-level children, both

elements. Both are assigned to the default slot. The slot attribute on the span has no effect on the distribution, because the span isn't a top-level child.

The first span is assigned into the title slot. The div, which has no slot attribute, is assigned to the default slot. The final span, which has a slot name that doesn't appear in the shadow tree, doesn't show up in the flattened tree, and doesn't render.

A slot with no name attribute acts as the default slot for any children that don't have a slot attribute. If a child's slot attribute doesn't match any named slot element in the shadow tree, that child doesn't appear at all.

The process of turning the light DOM and shadow DOM trees into a single tree for rendering is called flattening the tree. While the elements don't render, they are included in the flattened tree, so they can take part in event bubbling, for example.

The shadow tree is separate from the element's children. You can think of this shadow tree as part of the component's implementation, which outside elements don't need to know about. The element's children are part of its public interface.

Other bubbling events are retargeted as they bubble up the tree. Retargeting adjusts the event's target so that it represents an element in the same scope as the listening element.

In spec language, a slot's distributed nodes are the assigned nodes, with any slots replaced by their assigned nodes or fallback content. So in the example above, #child-slot has one distributed node, the span. You can think of the distributed nodes as the list of nodes that take the place of the slot in the rendered tree.

Light domexample

Custom property mixins are a feature built on top of the custom property specification. Basically, the mixin is a variable that contains multiple properties:

Polymer provides a declarative mechanism for adding a shadow tree using a DOM template. When you provide a DOM template for an element, Polymer attaches a shadow root for each instance of the element and copies the template contents into the shadow tree.

Styles inside a shadow tree are scoped to the shadow tree, and don't affect elements outside the shadow tree. Styles outside the shadow tree also don't match selectors inside the shadow tree. However, inheritable style properties like color still inherit down from host to shadow tree.

The MLO® High Performance Band Pass Filters exhibit low insertion loss within wide pass bands, steep roll-offs, and very high rejection of out of band frequencies. MLO® Band Pass Filters support many of frequency bands and multiple wireless standards, and are less than 1.0mm in thickness.

Note that the template includes a