Light DOM

Overview

Lightning Web Components typically render in Shadow DOM, which provides style encapsulation and DOM isolation. However, you can opt into Light DOM rendering for specific use cases where Shadow DOM restrictions are too limiting.

Light DOM is available in API version 58.0 and later. Use it when you need direct DOM access from parent components or better integration with global styles.

Shadow DOM vs Light DOM

Shadow DOM (Default)

Encapsulated styles: CSS defined in the component only affects that component
Isolated DOM: Parent components cannot query child component internals
Standard behavior: Default for all Lightning Web Components

Shared styles: Component inherits styles from parent and global CSS
Accessible DOM: Parent components can query child component elements
Legacy compatibility: Better integration with older Salesforce features

Enabling Light DOM

Set the renderMode static property to 'light':

// lightDomQueryChild.js
import { LightningElement } from 'lwc';

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

    handleButtonClick() {
        // Within Light DOM components, use this.querySelector
        // instead of this.template.querySelector
        this.querySelector('p.lightDomParagraph').innerText =
            'Text changed by child';
    }
}

Source: force-app/main/default/lwc/lightDomQueryChild/lightDomQueryChild.js:3-11 Update the template with the lwc:render-mode directive:

<!-- lightDomQueryChild.html -->
<template lwc:render-mode="light">
    <div class="slds-var-p-around_small">
        <p class="lightDomParagraph">Click any button to change this text</p>
        <div class="slds-var-m-top_small">
            <lightning-button
                onclick={handleButtonClick}
                label="Change Text"
            ></lightning-button>
        </div>
    </div>
</template>

Source: force-app/main/default/lwc/lightDomQueryChild/lightDomQueryChild.html:1-11

Querying Light DOM Elements

From Within the Component

Use this.querySelector() instead of this.template.querySelector():

import { LightningElement } from 'lwc';

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

    handleButtonClick() {
        // Light DOM: use this.querySelector
        this.querySelector('p.lightDomParagraph').innerText =
            'Text changed by child';
    }
}

From Parent Components

Parent components can directly access elements inside Light DOM children:

// lightDomQuery.js
import { LightningElement } from 'lwc';

export default class LightDomQuery extends LightningElement {
    handleButtonClick() {
        // Elements inside Light DOM child components are directly accessible
        this.template.querySelector('p.lightDomParagraph').innerText =
            'Text changed by parent';
    }
}

Source: force-app/main/default/lwc/lightDomQuery/lightDomQuery.js:4-8

In Shadow DOM, parent components cannot query elements inside child components. Light DOM removes this restriction.

Key Differences

DOM Queries

Shadow DOM:

// Access own elements
this.template.querySelector('.my-element');

// Cannot access child component internals
this.template.querySelector('c-child .internal'); // Returns null

Light DOM:

// Access own elements (no template property)
this.querySelector('.my-element');

// Can access child component internals if child is also Light DOM
this.querySelector('c-child .internal'); // Works!

Event Handling

Shadow DOM:

Events bubble through shadow boundaries
event.target may be retargeted

Light DOM:

Standard DOM event propagation
event.target is the actual element

Styling

Shadow DOM:

/* Styles are scoped to component */
.my-class {
    color: blue;
}

Light DOM:

/* Styles can be affected by parent/global CSS */
.my-class {
    color: blue; /* May be overridden by parent styles */
}

Use Cases for Light DOM

1. Third-Party Library Integration

Some libraries need direct DOM access:

import { LightningElement } from 'lwc';
import jQueryLib from '@salesforce/resourceUrl/jQuery';
import { loadScript } from 'lightning/platformResourceLoader';

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

    async renderedCallback() {
        await loadScript(this, jQueryLib);
        // jQuery can now access component elements
        window.$('.my-element').fadeIn();
    }
}

2. Global Style Application

Apply Salesforce Lightning Design System (SLDS) utilities:

<template lwc:render-mode="light">
    <div class="slds-grid slds-wrap">
        <div class="slds-col slds-size_1-of-2">
            <!-- SLDS utilities work directly -->
        </div>
    </div>
</template>

3. Accessibility Testing Tools

Some accessibility testing tools work better with Light DOM:

import { LightningElement } from 'lwc';

export default class AccessibleForm extends LightningElement {
    static renderMode = 'light';
    
    // Accessibility tools can fully inspect the DOM tree
}

4. Parent-Child DOM Manipulation

When parent needs direct control over child elements:

import { LightningElement } from 'lwc';

export default class ParentComponent extends LightningElement {
    handleHighlight() {
        // Directly manipulate child component's elements
        const childElement = this.template.querySelector('c-light-child .highlight');
        childElement.classList.add('highlighted');
    }
}

Limitations

Light DOM has important limitations compared to Shadow DOM. Consider these carefully before using Light DOM.

No style encapsulation: Component styles can conflict with parent/global styles
No slot support: <slot> elements don’t work in Light DOM
Security considerations: More vulnerable to XSS if not careful with DOM manipulation
Performance: Shadow DOM can have better performance in some scenarios

Migration Considerations

Converting from Shadow DOM to Light DOM

Add static renderMode = 'light'; to the class
Add lwc:render-mode="light" to the template
Replace this.template.querySelector() with this.querySelector()
Replace this.template.querySelectorAll() with this.querySelectorAll()
Remove <slot> usage (not supported in Light DOM)
Review CSS for potential conflicts with global styles

Example

Before (Shadow DOM):

import { LightningElement } from 'lwc';

export default class MyComponent extends LightningElement {
    handleClick() {
        this.template.querySelector('.my-element').focus();
    }
}

After (Light DOM):

import { LightningElement } from 'lwc';

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

    handleClick() {
        this.querySelector('.my-element').focus();
    }
}

Best Practices

Default to Shadow DOM: Only use Light DOM when you have a specific need
Namespace CSS classes: Prevent style conflicts by using unique class names
Document the choice: Comment why Light DOM is needed for future maintainers
Test thoroughly: Ensure no style conflicts with parent components
Validate accessibility: Light DOM can affect screen reader behavior

When NOT to Use Light DOM

Reusable components: Shadow DOM provides better encapsulation
Style isolation needed: Components that should look the same everywhere
Using slots: Slots only work in Shadow DOM
Security-sensitive: Shadow DOM provides an extra layer of isolation

Get Started

Basics

Component Composition

Event Handling

Data Access

Component Features

Navigation

Styling

Advanced Topics

Guides

Light DOM

Overview

Shadow DOM vs Light DOM

Shadow DOM (Default)

Light DOM

Enabling Light DOM

Querying Light DOM Elements

From Within the Component

From Parent Components

Key Differences

DOM Queries

Event Handling

Styling

Use Cases for Light DOM

1. Third-Party Library Integration

2. Global Style Application

3. Accessibility Testing Tools

4. Parent-Child DOM Manipulation

Limitations

Migration Considerations

Converting from Shadow DOM to Light DOM

Example

Best Practices

When NOT to Use Light DOM

​Overview

​Shadow DOM vs Light DOM

​Shadow DOM (Default)

​Light DOM

​Enabling Light DOM

​Querying Light DOM Elements

​From Within the Component

​From Parent Components

​Key Differences

​DOM Queries

​Event Handling

​Styling

​Use Cases for Light DOM

​1. Third-Party Library Integration

​2. Global Style Application

​3. Accessibility Testing Tools

​4. Parent-Child DOM Manipulation

​Limitations

​Migration Considerations

​Converting from Shadow DOM to Light DOM

​Example

​Best Practices

​When NOT to Use Light DOM

​Related Resources

Overview

Shadow DOM vs Light DOM

Shadow DOM (Default)

Light DOM

Enabling Light DOM

Querying Light DOM Elements

From Within the Component

From Parent Components

Key Differences

DOM Queries

Event Handling

Styling

Use Cases for Light DOM

1. Third-Party Library Integration

2. Global Style Application

3. Accessibility Testing Tools

4. Parent-Child DOM Manipulation

Limitations

Migration Considerations

Converting from Shadow DOM to Light DOM

Example

Best Practices

When NOT to Use Light DOM

Related Resources