Getting closer to Shadow DOM V1

April 6, 2017 4:18 pm Published by Leave your thoughts

Some of you may already have noticed, that Starcounter 2.3 brings us yet another step closer to WebComponents V1. This time, it’s about Shadow DOM.

Shadow DOM v0 and V1 translations

Latest <starcounter-include> is able to translate your Shadow DOM layout compositions between V0 and V1 syntax (both ways). That means you can start preparing and migrating your compositions for V1 one by one while still running in stable V0 environment. It applies as well for default compositions in <template is="declarative-shadow-dom"> (former <template is="starcounter-composition">) as for specific one for merged partial views. Moreover it will let you mix both versions in the same composition. Translation is done by translate-shadowdom package.

You can check how this translation works online, or even use it to automatically translate your own web components. It’s available as a bower and npm package.

V1 used if available

Another significant change is that <starcounter-include> will now use Shadow DOM V1 API, if available. This lets you use faster, (hopefully) native implementation and brings you sooner to up-to-date spec. As stated above the element is able to translate your compositions both ways. So, in case you still have some of them written in V0 syntax we will translate them to run in V1. Luckily they are almost 100% compatible, however there are some details you need to be aware of.

There is simple and complementary list of differences made by Hayato Ito – the editor of Shadow DOM spec, available at

The most important for us are:

  1. V1 introduces fallback contents which was not available in V0 – it’s really cool feature, but if you are targeting V0 environments you need to live without it, or implement it by yourself.
  2. V1 no longer supports /deep/ and ::shadow selectors – they were performance problem from very beginning and were deprecated for a long time. Now, in CSS you need to simply stop using them, maybe you would have to expose something in light DOM, in JS you will have to manually pierce through Shadow DOM, like: document.querySelector('.selector .for.shadow-host').shadowRoot.querySelector('')
  3. V1 supports only compound selectors for distributed nodes – they were also performance problem. In V0 you were able to do selectors like ::content .foo .bar, in V1 you are only able to do ::slotted(.foo) which means ::content > .foo. Therefore you will have to slightly redesign your selectors if you were using those. In JS you are naturally able to query for those using .assignedNodes(), for example: shadowRoot.querySelector('slot').assignedNodes()[0].querySelector. In CSS you may need to probably move some styling to the light DOM.
    During translation we will translate ::content .foo .bar to ::slotted(.foo) and add a warning both in code and in console.

Therefore, please test if your compositions works in both environments (if you are using both): V1 (native Chromium) and V0 (old webcomponentsjs polyfill).

Useful links

All above is delivered starting from Starcounter

Tags: , , ,

Categorised in: ,

This post was written by Tomek Wytrebowicz

Leave a Reply

Your email address will not be published. Required fields are marked *