You're viewing docs for an older version of Lit. Click here for the latest version.


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, Window or Document).
  • After first paint, if you're adding a lot of listeners and first paint performance is critical.

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.

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.


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 Window, Document, or some element in the main DOM–you should add the listener in connectedCallback and remove it in disconnectedCallback.

  • Removing the event listener in disconnectedCallback ensures 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.


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 Promise/setTimeout line yields to the browser

See firstUpdated in the Lifecycle documentation for more information.

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.

When you add an event listener imperatively, using addEventListener, you can specify various event listener options. For example, to use a passive event listener in plain JavaScript you'd do something like this:

The eventOptions decorator allows you to add event listener options to a listener that's added declaratively in your template.

Using decorators. Decorators are a proposed JavaScript feature, so you’ll need to use a compiler like Babel or TypeScript to use decorators. See Using decorators for details.

The object passed to eventOptions is used as the options parameter to addEventListener.

More information:

Fire an event from a LitElement-based component

Permalink 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 component

Permalink 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.

In plain HTML and JavaScript, this would be the addEventListener API:

When working with events and shadow DOM, there are a few things you need to know about.

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.

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 composedPath:

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 composed and bubbles flags to true:

See the MDN documentation on custom events for more information.