Light DOM in LWC

When discussing Lightning Web Components (LWCs), Light DOM enables the linkage of parent-child components and their visibility within them. This article provides an introduction to the fundamentals of Light DOM in LWCs to ensure that the complete functionality of this fantastic feature is well comprehended.

What is Light DOM?

One of the key concepts in LWC is the concept of light DOM. To make things easier to understand, in web development, the Document Object Model (DOM) is a programming interface that represents the structure of HTML and XML documents. The DOM basically defines how web pages are accessed and manipulated in the browser.

Understanding Light and Shadow DOM

First of all, let’s go over Shadow DOM. It encapsulates the DOM structure of an LWC. This gives developers the ability to share a component and protect it from being manipulated by arbitrary HTML, CSS, and JavaScript. The internal DOM structure is called the shadow tree, and it affects how you work with CSS, events, and the DOM.

In Light DOM, as opposed to Shadow DOM, the component content is attached to the host element of its shadow tree. It can then be accessed like any other content in the document host, providing similar behavior to content that is not bound by shadow DOM.

It is important to keep in mind that the DOM is not dependent on any particular programming language. Any language or framework used to create a web application would likely allow access to the DOM and its elements in some way.

Guidelines and best practices for Light DOM

Some basic use guidelines are the following:

  • Light DOM exposes your components to DOM scraping, so if you are working with sensitive data, using shadow DOM is recommended.
  • Since the DOM is open for traversal by other components and third-party tools, you are responsible for securing your light DOM components. While shadow DOM prevents unauthorized access into the shadow tree, Light DOM is unable to provide the same level of DOM encapsulation benefits.
  • As a reminder, you can nest a light DOM child component using both light DOM and shadow DOM in your app.
  • It is recommended to encapsulate deeply nested light DOM components in a single shadow DOM component at the top level. Then, you can share styles between all the components under the shadow root.
  • Be careful when querying elements or injecting styles at the document level. A shadow tree can sit between the document and your component.
  • You can override shadow DOM styles via CSS Custom Properties and ::part. However, the component owner is in charge of exposing the extension points, which prevents downstream consumers from styling arbitrary elements.

Light DOM limitations

As great as Light DOM may sound, it has some limitations, listed below.

  • Distributing components rendered in light DOM is not supported. Component references in a managed package use the c namespace and would result in a namespace conflict.
  • Base components are always rendered in shadow DOM.
  • Aura components can’t use light DOM. However, an Aura component can contain an LWC component that uses light DOM.
  • Lifecycle hooks on slots are never invoked since the slot element does not render in the DOM.
  • Using slots inside a for:each iterator is not supported.

When to use Light DOM instead of Shadow DOM

Generally, shadow DOM is the recommended way to author components due to its strong encapsulation. That is due to the fact that it hides your component’s internals so customers can only use its public API. However, there are certain cases where shadow DOM is not suitable for use:

  • Building a highly customizable UI, where you want to have complete control over a web app’s appearance.
  • Using third-party libraries. Many popular libraries are not compatible with shadow DOM.

Light DOM vs Shadow DOM

From the Salesforce Developers’ official documentation, we can extract the following table to compare the main characteristics of Light and Shadow DOM:

How to enable Light DOM in your LWC

To enable Light DOM, you may start by setting the renderMode static property in your component class. Remember that the default renderMode is Shadow.

import { LightningElement } from 'lwc'

export default class LightDomApp extends LightningElement {
  static renderMode = 'light';

 Then, use the lwc:render-mode root template directive, which is required for components using light DOM.

<template lwc:render-mode='light'>
    <p>Salesforce Light DOM</p>

It is worth noting that changing the value of the renderMode static property after instantiation does not impact whether components render in light DOM or shadow DOM.

Working with Light DOM

In this section we will be covering three of the many capabilities your components can perform. To keep reading and understanding all of them, please make sure to check the following link.

Composition of Light DOM

As you might have noticed by now, your app can contain components that use either Shadow DOM or Light DOM. A Light DOM component can contain a Shadow DOM, and a Shadow DOM component can contain a Light DOM component. However, if you have deeply nested components, considering a single shadow DOM component at the top level with nested light DOM components might be a good idea. This structure allows you to freely share styles between all child components within the one shadow root.

Using Light DOM for Event Propagation in LWC

Shadow DOM retargets any events crossing up the shadow boundary, and some property values change to match the scope of the listener. With Light DOM, events are not retargeted, and identifying the UI element that triggered the event is much easier – since you won’t be getting a reference from the underlying component.

Using the Light DOM to Access Elements in LWC

Accessing elements in Light DOM can be done by using the document.querySelector(‘p’) method. This allows us to access and manipulate elements as needed.

For any previous references, in Shadow Mode, we would use this.template.querySelector, and in Light DOM we may use this.querySelector.


Light DOM provides a simple and efficient approach to building intricate Lightning Web Components (LWCs). As illustrated in this article, Light DOM is a useful tool that can be selectively employed, depending on the developer’s preferences. This grants Salesforce developers the autonomy to decide which component rendering approach is most suitable when creating LWCs.


No Comments

Sorry, the comment form is closed at this time.