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 (LWS). 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