February 12, 2024
  • All
  • Announcements
  • Stencil
  • stencil

Enhanced Support for Slots outside of Shadow DOM

Stencil Team

We’re happy to announce several improvements to the experience of using slots without using the Shadow DOM in Stencil components. Driven by lots of community feedback, this popular feature should now work in the majority of cases.

Slots in the Light DOM?

Slots, a core element of web components, are placeholders inside a web component that you can fill with your own markup. Slots are native to the Shadow DOM, but Stencil polyfills the behavior to work for non-shadow components as well. Over time, it’s seen heavy adoption in the Stencil community, and with this popularity, some limitations started to be discovered.

With this in mind, the Stencil team rolled up their sleeves and got to work making the experience better.

Bug Smash

There are many issues that have been addressed over time (view the complete list here), but the most impactful ones include:

  • Elements rendering in the wrong order. When a parent component’s template contains a child component which it passes its slot content into, the nested slot’s content can end up in the wrong order.
  • Incorrect application of the ‘hidden’ attribute to slotted content. Slotted content may incorrectly get the ‘hidden’ attribute applied when slotted through multiple levels of components. This was most noticeable when the final destination did not wrap the slot in an additional element (like a span or div).
  • Adding/removing children in Stencil slots when using React. When React manages the children of the Stencil container tag, it fails to add and remove them correctly. 

Some additional changes related to slots being used in components leveraging scoped encapsulation were also made. These changes are behind a second configuration flag and are intended to more closely align Stencil’s slot polyfill with the behavior of the native Shadow DOM. A list of changes controlled by this flag can be found here.

With the recent release of Stencil v4.12.1, we believe that all major light DOM slot issues have been resolved.

Opting into the Enhancements

All of the above slot enhancements to the Stencil runtime have been added over the course of Stencil v4. While we’re confident in the positive impact these changes have made, they’ve been marked as experimental in v4 in order to give the community time to test the fixes in their Stencil components. We intend to make these enhancements the default in the release of Stencil v5, happening later this year.

To opt into the fixes, update your Stencil config file to set the experimentalSlotFixes and experimentalScopedSlotChanges extras options to true: 

// stencil.config.ts
import { Config } from '@stencil/core';

export const config: Config = {
  extras: {
    experimentalSlotFixes: true,
    experimentalScopedSlotChanges: true
  }
};

Read more about how to configure the slot fixes here.

Start Testing Slot Changes Now

With a majority of this work wrapped up, we encourage you to enable and test out these changes so we can verify their correctness in a larger set of use cases. The plan is that these flags will be enabled by default in Stencil v5. If anyone still experiences any of the issues claimed to be fixed by these config flags (or encounters any new issues), please open a new issue with a minimal reproduction case. Opening new issues will help us stay organized and prioritize fixes!

Please note that these recent fixes do not address SSR-related issues that were sometimes mentioned in various Slot PRs. Rest assured, SSR-related issues are on our list to address soon!


Lastly, we want to give a HUGE shoutout to @johnjenkins for his work on these Slot issues. His effort was immensely helpful both as a starting point and a reference while working through them. Thank you from all of us on the Stencil team!

Stencil Team

Related Posts