DOM Access Containment

A Lightning component can only traverse the DOM and access elements that it created. This behavior prevents the anti-pattern of reaching into DOM elements owned by other components.

It’s an anti-pattern for any component to “reach into” another component, regardless of namespace, because it breaks encapsulation. Lightning Locker only prevents cross-namespace access. Your good judgment should prevent cross-component access within your own namespace as it makes components tightly coupled and more likely to break.

Lightning web components can’t use the window or document global properties to query for DOM elements when Lightning Locker is enabled. For example, use this.template.querySelector() instead of document.querySelector(). The document.querySelector() method isn’t supported for Shadow DOM.

If your org has Lightning Web Security (LWS) enabled instead of Lightning Locker, component access to the DOM is controlled by the browser through Shadow DOM, which is a web standard implemented in web browsers. LWS enforces a closed shadowRoot by requiring mode to be closed, which provides additional encapsulation restrictions. See ShadowRoot.mode in MDN. Although we don’t recommend using window and document global properties directly, LWS permits access to those properties within an LWC component and its parent hierarchy.

Let’s look at a sample component that demonstrates DOM containment.

The c:domLocker component creates a <div> element and a lightning:button component.

Here’s the client-side controller that peeks around in the DOM.

The following methods are valid DOM access because the elements are created by c:domLocker.

  • cmp.getElements() :- Returns the elements in the DOM rendered by the component.
  • cmp.find() :- Returns the div and button components, identified by their aura attributes.
  • cmp.find("div1").getElement() :- Returns the DOM element for the div as c created the div.
  • event.getSource().get("v.name") :- Returns the name of the button that dispatched the event; in this case, myButton.

You can’t use cmp.find("button1").getElement() to access the DOM element created by lightning:button. Lightning Locker doesn’t allow c:domLocker to access the DOM for lightning:button because the button is in the lightning namespace and c:domLocker is in the c namespace.

If you uncomment the code for cmp.find("button1").getElement(), you see an error:

This code doesn’t return an error if your org has LWS enabled instead because cross-namespace component use is allowed with LWS. See How Lightning Web Security Compares to Lightning Locker.

See Also