Access Elements the Component Owns

To access elements rendered by a component with standard DOM APIs, use querySelector() with this.template or this. To locate elements in the DOM without a selector, use refs.

Don’t use the window or document global properties to query for DOM elements. See DOM Access Containment. Also, we don’t recommend using JavaScript to manipulate the DOM unless you're working with a third-party library via lightning/platformResourceLoader. It's better to use the Lightning Web Components HTML directives to write declarative code.

The standard way to access elements in the DOM is to use querySelector(). To locate shadow DOM nodes, use querySelector() or querySelectorAll() on this.template. For light DOM nodes, use one of those methods on this.

You can also use {element}.template.querySelector.

Use these methods to look for the elements that your component rendered.

  • The order of elements is not guaranteed.
  • Elements not rendered to the DOM aren’t returned in the querySelector result.
  • Don’t use ID selectors with querySelector. The IDs that you define in HTML templates may be transformed into globally unique values when the template is rendered. If you use an ID selector in JavaScript, it won’t match the transformed ID.
  • For light DOM components, this.querySelector() searches through elements outside of the immediate template, such as light DOM children. Use a more specific selector to narrow the scope of the method.
  • If the component runs in an org with Lightning Locker enabled, be aware of a potential memory leak. If possible, the org should enable Lightning Web Security. Alternatively, consider using refs instead of querySelector.
  • Place light DOM components within a shadow DOM component. Lightning Locker and LWS don’t support light DOM components outside shadow DOM.

The lwc-recipes repo has a miscDomQuery component that demonstrates DOM querying using querySelectorAll.

Refs locate DOM elements without a selector and only query elements contained in a specified template. First, add the lwc:ref directive to your element and assign it a value. To call that reference, use this.refs. In this example, the <div> element has the directive lwc:ref="myDiv", which this.refs references to access the <div> at runtime.

You must define the directive lwc:ref before calling this.refs. If you call this.refs for a nonexistent ref, it returns undefined. If the template contains duplicate lwc:ref directives, this.refs references the last <div>.

this.refs is a plain, read-only object. Trying to add, modify, or delete properties from within its component causes a runtime error. Its key is a string, and its value is a DOM element. The syntax for this.refs is the same for referencing elements in light DOM and shadow DOM.

Refs are configurable and writable, so refs defined in a component overwrite those from LightningElement.prototype.

You can’t apply lwc:ref to <template> elements, or to <slot> elements in light DOM.

If you place lwc:ref in a for:each or iterator:* loop, the template compiler throws an error.

this.refs refers to the most recently rendered template in a multi-template component. When the template changes, the this.refs object will change too.

To conditionally define an element based on <template lwc:if={boolean}>, create multiple child templates under one parent template. In this example, this.refs.toggleDarkMode refers to the element inside of whichever child template is rendered.

AVAILABLE API VERSIONS
Available in LWC API v62.0 and later

To access the HTMLElement of a Lightning web component from within a callback function, use this.hostElement in your component. The hostElement property lets you retrieve a property on the HTMLElement class. You can apply it to shadow DOM or light DOM components.

This example returns this.hostElement in a light DOM component.

In light DOM, this.template.host returns undefined. In shadow DOM, this.hostElement is interchangeable with this.template.host.

See Also