lwc-light-dom

# LWC Light DOM

Activate this skill when a Lightning Web Component needs to break out of shadow DOM isolation — usually because search engine crawlers, a third-party JavaScript library, a global stylesheet, or accessibility tooling cannot see into the shadow tree. Light DOM is an escape hatch, not a default.

---

## Before Starting

Gather this context before switching a component's render mode:

- What is the real blocker? (SEO indexing on Experience Cloud, a tooltip/chart library's `document.querySelector`, a global CSS system, screen-reader or analytics tooling.) Do not reach for light DOM to "fix" a CSS specificity issue you have not tried to solve with styling hooks.
- Where will the component run? Internal Lightning Experience pages rarely need light DOM. Experience Cloud LWR sites are the common home for it. Experience Cloud Aura sites and managed-package distribution have extra rules.
- Will the component ship through a managed package? Salesforce explicitly recommends **against** light DOM for managed-package components because their styles would leak into consumer orgs.
- Is the LWC ecosystem still subject to Lightning Web Security (LWS)? Yes — LWS sandboxes JavaScript regardless of render mode.

---

## Core Concepts

### Opting Into Light DOM

Light DOM is enabled two ways and both must line up:

1. On the class, set the static property `renderMode`:
   ```javascript
   import { LightningElement } from 'lwc';
   export default class FaqAccordion extends LightningElement {
       static renderMode = 'light';
   }
   ```
2. On the root `<template>` tag, set `lwc:render-mode="light"`. You cannot mix modes within one template — the root template sets the mode for the whole component.

Once both are in place, `this.template` no longer wraps a shadow root and standard DOM APIs such as `document.querySelector`, external CSS, and native screen-reader traversal can see the rendered markup.

### Scoped vs Unscoped Styles (the `*.scoped.css` Convention)

Light DOM styles **bleed** by default because there is no shadow boundary to contain them. Salesforce provides the `*.scoped.css` file-naming convention: a file named `faqAccordion.scoped.css` is compiled with synthesized, component-specific attribute selectors so its rules stay tied to this component's elements. A plain `faqAccordion.css` sitting next to a light-DOM component is **global** and will leak to every consumer on the page. You typically want the scoped file for component-owned styles and, if you need intentional global theming, an additional unscoped file — not the other way around.

### Why Light DOM Costs You Encapsulation

In shadow DOM, styles, IDs, and event retargeting stay inside the component. Light DOM gives that up on purpose: global CSS can reach in, so can third-party scripts, so can `aria` relationships that depend on IDs being visible across the page. That is the whole point — but it also means naming collisions, leaked selectors, and unsanitized HTML become your responsibility.

### Interop: Third-Party Libraries, SEO, Accessibility

- **Third-party libraries** (d3, Chart.js, tooltip/popover libs, any code that calls `document.querySelector`) cannot traverse into a shadow root from outside. Light DOM restores that access.
- **SEO on Experience Cloud LWR sites** requires that crawlers see the rendered HTML. Shadow DOM content is not reliably indexed; light DOM content is plain markup in the page source.
- **Accessibility and analytics tooling** (screen-reader testing harnesses, Selenium/WebDriver automation, heatmap and analytics scripts) can reach light-DOM elements with standard selectors, which simplifies integration.

### Lightning Web Security Still Applies

A common mistake is to assume light DOM disables LWS. It does not. LWS continues to sandbox JavaScript, intercept global APIs, and enforce namespace isolation. Light DOM only changes where the rendered markup lives — it does not open JS back up to the page.

### Managed Packages: Do Not Ship Light DOM

Salesforce guidance is explicit: do not distribute light-DOM components inside managed packages. Their un-encapsulated styles would bleed into any consumer org's pages, and consumers cannot scope them after install.

---

## Common Patterns

### Experience Cloud LWR Component That Must Be Indexed

**When to use:** Public-facing FAQ, blog post, product description, or marketing module on an LWR site that needs to rank in search.

**How it works:** Set `static renderMode = 'light'` on the class, `lwc:render-mode="light"` on the root template, and put component styles in `<name>.scoped.css`. Render the user-visible text as plain DOM (no shadowed slot tricks) so the crawler sees it.

**Why not the alternative:** Leaving the component in shadow DOM leaves the content invisible to many crawlers and broken for some third-party SEO/analytics scripts.

### Third-Party Library Integration

**When to use:** A library like a tooltip, chart, or drag-and-drop framework needs to call `document.querySelector` or attach listeners to a specific element inside the component.

**How it works:** Switch to light DOM, give the target element a stable class or ID, and let the library's external script find it from the document. Keep JS sandboxed — LWS will still enforce API restrictions.

**Why not the alternative:** Trying to bridge shadow DOM with `::part`, custom events, or manual ref passing usually ends up fighting the library and is fragile across versions.

### Intentional Global Theming From An Experience Cloud Branding Set

**When to use:** The site's branding system (fonts, color tokens, spacing) must reach all public-facing components uniformly.

**How it works:** Use light DOM for the components that must receive global theming, and let Experience Cloud branding CSS flow in. Keep layout and component-specific visual rules in the `*.scoped.css` file so they do not leak outward.

---

## Decision Guidance

| Situation | Recommended Approach | Reason |
|---|---|---|
| SEO indexing required on an Experience Cloud LWR site | Light DOM with `*.scoped.css` | Crawlers need to see rendered markup directly |
| Internal LEX-only admin or productivity component | Shadow DOM (default) | Encapsulation and style isolation win; no external consumers need DOM access |
| Third-party JS library must query/attach to a specific element | Light DOM | Libraries calling `document.querySelector` cannot cross the shadow boundary |
| Reusable widget meant to be embedded in many pages / flows | Shadow DOM (default) | Prevents cross-page style leaks and collisions |
| Managed-package component shipped to consumer orgs | Shadow DOM (required by Salesforce guidance) | Light-DOM styles would leak into every consumer org |
| Global theming system (Experience Cloud branding) must flow in | Light DOM for the themed components | Shadow DOM blocks inherited theming by design |
| Accessibility/screen-reader or analytics tooling needs to traverse | Light DOM with care | External tools can read the DOM; sanitize any user-provided HTML |

---

## Recommended Workflow

Step-by-step instructions for an AI agent or practitioner activating this skill:

1. Confirm the blocker — SEO, third-party DOM access, global styling, or a11y/analytics tooling. If none of these apply, stay in shadow DOM.
2. Verify the runtime and distribution model — LWR vs Aura vs internal LEX, and whether this ships through a managed package (if managed, stop and keep shadow DOM).
3. Enable light DOM — add `static renderMode = 'light'` in the JS and `lwc:render-mode="light"` on the root `<template>`.
4. Rename component CSS to `<name>.scoped.css` so styles do not bleed, and add a separate unscoped file only for deliberately global theme hooks.
5. Review sanitization, LWS behavior, and third-party script access — DOMPurify any user-controlled HTML; confirm LWS does not block the library's JS APIs.
6. Run the checker and validate with a smoke test on an Experience Cloud preview (view source, confirm content is in the page HTML) before release.

---

## Review Checklist

Run through these before marking work in this area complete:

- [ ] A concrete blocker (SEO, library DOM access, global theming, a11y tool) is documented for each light-DOM component.
- [ ] Both `static renderMode = 'light'` and `lwc:render-mode="light"` are set; no mixed-mode templates.
- [ ] Component styles live in `<name>.scoped.css`; any intentional global styles are in a clearly named unscoped file.
- [ ] No `:host` / `:host-context` selectors remain in the component CSS (they do not exist in light DOM).
- [ ] Component is NOT being distributed inside a managed package.
- [ ] Any user-supplied HTML is run through DOMPurify or an equivalent sanitizer before injection.
- [ ] Experience Cloud preview shows the content in the raw HTML source (for SEO components).
- [ ] LWS-sandboxed JS still functions with the third-party library end-to-end.

---

## Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. **Plain `<name>.css` in a light-DOM component is global** — one stray selector can leak across the whole page. Use `<name>.scoped.css`.
2. **You cannot mix render modes inside one template** — the root `<template>` sets it for the entire component tree it owns.
3. **`:host` selectors do nothing in light DOM** — there is no shadow host. Refactor to a wrapper element with a class.
4. **LWS is still on** — light DOM does not re-expose blocked JS globals or disable the sandbox.
5. **Managed-package components must stay shadow DOM** — Salesforce's docs explicitly warn against shipping light DOM through managed packages because of style leaks.
6. **Experience Cloud Aura sites behave differently from LWR sites** — confirm the site template before assuming light DOM fixes the SEO problem.
7. **Toggling an existing component from shadow to light is a breaking change** — existing consumers may rely on style isolation, and removing it can regress their layouts.

---

## Output Artifacts

| Artifact | Description |
|---|---|
| Render-mode decision memo | Which components stay shadow DOM and which move to light, with the blocker cited |
| Scoped-styles layout | Mapping of `<name>.scoped.css` vs unscoped global files per component |
| Checker report | File-level findings for missing `*.scoped.css`, forbidden `:host` selectors, and managed-package conflicts |
| LWS / sanitization review | Confirmation that LWS still passes and user-supplied HTML is sanitized |

---

## Related Skills

- `lwc/lwr-site-development` — use when the light-DOM decision is driven by an LWR Experience Cloud site and you need the full site-build context.
- `lwc/experience-cloud-lwc-components` — use for Experience Cloud-specific component targets, capabilities, and `js-meta.xml` shape.
- `lwc/lwc-security` — use for LWS, CSP, and DOM sanitization decisions that accompany any light-DOM adoption.
- `lwc/lwc-styling-hooks` — use first when the problem looks like a CSS issue; styling hooks often solve it without losing encapsulation.