Where to add your event listenersPermalink to “Where to add your event listeners”
You need to add event listeners in a method that is guaranteed to fire before the event occurs. However, for optimal loading performance, you should add your event listener as late as possible.
The most common ways to add an event listener:
- Declaratively, in your component's template
- In the component constructor, for listeners added on the component itself.
- In the
connectedCallback, for listeners that need to reference DOM outside the component (for example,
- After first paint, if you're adding a lot of listeners and first paint performance is critical.
Add declarative event listenersPermalink to “Add declarative event listeners”
You can use lit-html
@event bindings in your template to add event listeners to your component.
Declarative event listeners are added when the template is rendered. This is usually the best way to add listeners to elements in your templated DOM.
Add event listeners in the constructorPermalink to “Add event listeners in the constructor”
If you need to listen for an event that might occur before your component has been added to DOM, you might need to add the event listener in your component's constructor.
The component constructor is a good place to add event listeners on the host element itself.
Add event listeners in Permalink to “Add event listeners in connectedCallback”
connectedCallback is a lifecycle callback in the custom elements API.
connectedCallback fires each time a custom element is appended into a document-connected element. See the MDN documentation on using custom elements lifecycle callbacks for more information.
If your component adds an event listener to anything except itself or its children–for example, to
Document, or some element in the main DOM–you should add the listener in
connectedCallback and remove it in
Removing the event listener in
disconnectedCallbackensures that any memory allocated by your component will be cleaned up when your component is destroyed or disconnected from the page.
Adding the event listener in
connectedCallback(instead of, for example, the constructor or
firstUpdated) ensures that your component will re-create its event listener if it is disconnected and subsequently reconnected to DOM.
Add event listeners after first paintPermalink to “Add event listeners after first paint”
Sometimes, you may want to defer adding an event listener until after first paint—for example, if you're adding a lot of listeners and first paint performance is critical.
LitElement doesn't have a specific lifecycle callback called after first paint, but you can use this pattern with the
firstUpdated lifecycle callback:
firstUpdated fires after the first time your component has been updated and called its
render method, but before the browser has had a chance to paint. The
setTimeout line yields to the browser
See firstUpdated in the Lifecycle documentation for more information.
Using Permalink to “Using this in event listeners”
this in event listeners
Event listeners added using the declarative (
@event) syntax in the template are automatically bound to the component.
Therefore, you can use
this to refer to your component instance inside any declarative event handler:
When adding listeners imperatively with
addEventListener, you'll need to bind the event listener yourself if you need a reference to the component instance. For example:
Or use an arrow function as a class field:
See the documentation for
this on MDN for more information.
Setting event listener optionsPermalink to “Setting event listener options”
When you add an event listener imperatively, using
eventOptions decorator allows you to add event listener options to a listener that's added declaratively in your template.
The object passed to
eventOptions is used as the
options parameter to
- EventTarget.addEventListener() on MDN for a description of the event listener options.
Use casesPermalink to “Use cases”
- Fire a custom event from a LitElement-based component.
- Handle a custom event fired by a LitElement-based component.
- Handle an event fired by a shadow DOM child of your component.
- Add event listeners imperatively.
Fire an event from a LitElement-based componentPermalink to “Fire an event from a LitElement-based component”
Fire a custom event:
Fire a standard event:
Handle an event fired by a LitElement-based componentPermalink to “Handle an event fired by a LitElement-based component”
If you want to listen to an event fired from a LitElement-based component from within another LitElement or from a lit-html template, you can use the lit-html declarative event syntax:
To listen to events fired from a LitElement-based component in other contexts, like HTML or another framework, use the standard mechanism for listening to DOM events.
Working with events and shadow DOMPermalink to “Working with events and shadow DOM”
When working with events and shadow DOM, there are a few things you need to know about.
Event bubblingPermalink to “Event bubbling”
Some events bubble up through the DOM tree, so that they are detectable by any element on the page.
Whether or not an event bubbles depends on the value of its
bubbles property. To check if a particular event bubbles:
See the MDN documentation on the Event interface for more information.
Event retargetingPermalink to “Event retargeting”
Bubbling events fired from within shadow DOM are retargeted so that, to any listener external to your component, they appear to come from your component itself.
When handling such an event, you can find where it originated from with
Custom eventsPermalink to “Custom events”
By default, a bubbling custom event fired inside shadow DOM will stop bubbling when it reaches the shadow root.
To make a custom event pass through shadow DOM boundaries, you must set both the
bubbles flags to
See the MDN documentation on custom events for more information.