Mixed Shadow Mode

10/01/2023

Featured in the Winter ‘23 release notes, Mixed Shadow Mode enables you to use the well-known JavaScript shadow DOM in older browsers where the synthetic shadow polyfill is applied. This polyfill is maintained and used in older versions of Microsoft Edge. By using it, you are one step closer to using the full advantages of native shadow, and ensuring that your applications are as swift and efficient as the ones that use it.

Key Understanding Concepts

In order to make the reading of this article more pleasant and comprehensible, we listed a few definitions of the key concepts in this section.

Shadow DOM

Shadow DOM is a standard that encapsulates the internal Document Object Model (DOM) structure of a web component. This gives developers the ability to share a component and protect the component from being manipulated by arbitrary HTML, CSS, and JavaScript.

Shadow Tree

In the context of Shadow DOM, a shadow tree is the internal DOM tree of a Shadow DOM element. It is a separate tree from the main DOM tree of the web page, and it is not accessible to the page’s scripts or styles. The Shadow Tree contains the elements and structure of the Shadow DOM component, and it is rendered separately from the main page. This allows the developer to create isolated, self-contained components that can be easily reused and composed within a web application.

Shadow Mode

Essentially, Shadow mode is a feature in the JavaScript programming language (although it can be applied to LWC since JavaScript is used) that allows developers to create a “shadow” or a copy of an object. This shadow object has the same properties and methods as the original object, but any changes made to the shadow object do not affect the original object. This allows developers to create reusable, modular components that can be easily included in a page without conflicts with other elements on the page.

Polyfill

Polyfills are code snippets (often, web JavaScript) specifically designed for outdated browsers that do not support new capabilities natively.

Synthetic Shadow Polyfill

They are a collection of Polyfills that implement Shadow DOM features and are published to npm under the @lwc/synthetic-shadow package. The synthetic shadow polyfill (i.e., @lwc/synthetic-shadow) is used to determine whether all of the components in an application operate in synthetic mode or native mode.

Synthetic Shadow and Shadow Mode

When a polyfill (Synthetic Shadow Polyfill) is utilized in the context of Salesforce’s LWC, it implements what we refer to as “the synthetic shadow DOM.” This provides Shadow DOM semantics in older browsers that do not support it, giving LWC a uniform experience throughout the Salesforce-supported browser matrix.

Though the prevalence of native DOM support has increased with the advent of the LWC era, certain applications still rely on artificial shadow polyfills to preserve backward compatibility. If these polyfills are removed, existing apps that rely on certain “escape hatches” that are not feasible in a native Shadow DOM environment may encounter broken experiences.

Mixed Shadow Mode, ultimately, opens up an incremental migration path for applications moving to native Shadow DOM by enabling the usage of both native and synthetic Shadow DOM in the same application. Hence, Mixed mode adds the capability for a component to use native Shadow DOM APIs even while the synthetic shadow polyfill is in place.

The two options for shadow semantics up until this point have been synthetic mode and native mode.

What is Mixed Shadow Mode?

With Mixed Shadow Mode, Lightning Web Components (LWC) can use native shadow DOM even when the synthetic shadow polyfill is applied.

Why and Where would you use it?

As covered below, this change applies to custom LWC in Lightning Experience, Experience Builder sites, and all versions of the Salesforce mobile app. This change also applies to LWC open source.

Why would you use it, you might be wondering? Well, nearly all major browsers now support shadow DOM. However, Salesforce maintains the synthetic shadow polyfill for legacy browsers such as older versions of Microsoft Edge. Even on browsers that enable shadow DOM, the polyfill is used to streamline development and testing. You can use mixed shadow mode to increase the efficiency and performance of native shadow in your app,

How to enable Mixed Shadow Mode

One thing to keep in mind is that Mixed Shadow Mode is disabled by default. You must contact Salesforce Customer Support to enable Mixed Shadow Mode.

How to enable Mixed Shadow Mode on a Component

We tried creating an LWC and adding this by ourselves. As we all know, scratch orgs in Salesforce have Nowadays, you can’t include it in the project-scratch-def.json, since there’s no documentation implying that this is possible. However, by adding the code snippet shown below in the JavaScript file of an LWC, it does work.

From the official Winter ’23 release notes of Salesforce, we can infer the following details.

To enable Mixed Shadow Mode on a Component, set the static shadowSupportMode property to any to enable Mixed Shadow Mode on a component.

// native.js 
import { LightningElement } from ‘lwc’; 
export default class NativeComponent extends LightningElement { 
  static shadowSupportMode = ‘any’; 
}

shadowSupportMode can include two different values:

any: renders the whole component subtree in native shadow DOM where possible. If the browser does not support Shadow DOM, the subtree renders in synthetic shadow.
reset: enables a subclass to opt out of receiving the shadowSupportMode value from its superclass. reset applies only if the component’s superclass is using any and no parent components are using any.

Considerations regarding polyfills

The synthetic shadow polyfill is included by default in Lightning Experience and Experience cloud. Reset defaults to synthetic shadow when the polyfill is present. In the case of no polyfill presence, shadowSupportMode has no impact and the components are rendered in native mode.
Slotted content is rendered in native shadow. This means that the content is not affected by how your browser renders the #shadow-root of the component containing the slot, and also that the content is not descended from the component it’s nested in. From this, we can extract that you can slot synthetic shadow content into a native shadow component.

Testing

Integration tests are currently available for Native Shadow Mode and Synthetic Shadow Mode in the Lightning Web Component framework. For Mixed Shadow Mode, a third testing mode will soon be made available. The Synthetic Shadow Polyfill will not interfere with components operating in native mode thanks to this testing environment.

Additionally, you may find any coverage holes in the LWC integration tests by using the current WPT (Web Platform Tests) test suite for Shadow DOM APIs.

You might be wondering what happens if a component uses both native and artificial shadow modes. Undoubtedly, tests on them are necessary! This will be made possible by LWC test utilities, which are getting updated soon to ensure these components can be tested. As the level of Shadow DOM support will not be taken into account when calculating a component’s shadow mode, it is additionally necessary to test the component to ensure that all employed APIs are accessible in both modes across the supported browser matrix.

Disadvantages of Mixed Shadow Mode

One of the drawbacks identified by the Developers is a potential, not-verified downside of existing components experiencing a slight performance degradation due to the logic forking required by mixed mode. However, the code to implement Mixed Shadow Mode will be non-trivial and will, according to the Developers, eventually be thrown away when all supported browsers have mature support for Shadow DOM.

Alternatives to Mixed Shadow Mode

Let’s say we don’t want to use Mixed Shadow Mode. One alternative could be to simply deprecate LWC’s synthetic Shadow DOM polyfill. This approach, however, is not practical because Salesforce experiences are made up of parts that are executed by many parties, and orchestrating such a changeover is practically impossible.

Salesforce Developers advise implementing a smooth transition path so that users may get ready for the native Shadow DOM rollout without being hindered.

Summary

As Salesforce plans to eventually deprecate their Synthetic Shadow Polyfill, Mixed Shadow Mode comes as a great feature for applications moving to native Shadow DOM by enabling the usage of both native and synthetic Shadow DOM in the same application. The usage and implementation of Mixed Shadow Mode can ensure the production of components that can be future-proof and minimize the amount of tech debt right from the beginning of the implementation.

Although it is somehow hard to grasp at first, Mixed Shadow Mode will allow developers to use native Shadow DOM even when the Synthetic Polyfill is applied, thus making the development of applications speedier, more efficient, and easier to migrate to native shadow in the future.