Lit Event Listeners

In Lit, information is usually passed up from child to ancestor components by dispatching custom events. This is a common pattern in web components more generally. Whilst events are a versatile and powerful way to communicate between components, they can also be a source of memory leaks and unexpected behaviour if not handled correctly.

Lit's @ declarative syntax

Lit allows event listeners to be declared using the @ syntax. This is a convenient way to add event listeners that also provides for consistent, automatic cleanup. These are defined in the component's render function in the HTML template. This method is highly recommended if adding an event listener to a child of the component.

@customElement('my-element')
export class MyElement extends LitElement {
  
  @property({ type: Number }) count = 0;

  render() {
    return html`
      <div>Count: ${this.count}</div>
      <button @click=${this.handleClick}>Click me</button>
    `;
  }

  handleClick() {
    this.count++;
  }
}

Imperatively adding event listeners

Event logic can be added in the connectedCallback lifecycle method. As the connectedCallback method is called every time the element is connected to the DOM, this provides consistency when adding event listeners if the disconnectedCallback is used to remove them. Lit's documentation states that this method should be used to add event listeners to elements outside the component's rendered template.

Imperatively removing event listeners

Event listeners should be removed in the disconnectedCallback lifecycle method. This is because it is called when the element is removed from the DOM. In conjunction with the event listeners added in the connectedCallback, this ensures a consistent approach to adding and removing event listeners. If implemented correctly, the same event listener will be added and removed every time the element is connected and disconnected from the DOM, preventing the possibility of memory leaks.

The callback function

Callback functions should not be anonymous functions, as when cleanup occurs, a different reference to the function is given to the removeEventListener method. This means that the event listener is not removed. Instead, the callback function should be a named function, which can be passed to the removeEventListener method. The this context is important to consider. With functions passed to the @ declarative syntax, the this context is automatically bound to the component. When functions are added using addEventListener(), the context of this is bound to the element upon which it is attached. Therefore, to maintain the context of this as being that of the component, we can use an arrow function (not anonymous) or manually bind the context. Making the functions a class property is a good way to store a reference for eventual event deregistration.

interface ScreenSize {
  width: number;
  height: number;
}

@customElement('my-element')
export class MyElement extends LitElement {
  
  @property() screenSize: ScreenSize = {
    width: window.innerWidth,
    height: window.innerHeight
  };

  handleResize(e: Event) {
    this.screenSize = {
      width: window.innerWidth,
      height: window.innerHeight
    };
  }

  handleResizeBound = this.handleResize.bind(this);

  connectedCallback() {
    super.connectedCallback();
    window.addEventListener('resize', this.handleResizeBound);
  }

  disconnectedCallback() {
    super.disconnectedCallback();
    window.removeEventListener('resize', this.handleResizeBound);
  }

  render() {
    return html`
      <div>Screen width: ${this.screenSize.width}</div>
      <div>Screen height: ${this.screenSize.height}</div>
    `;
  }
}

Adding event listeners in other lifecycle methods

Event listeners can also be added in other lifecycle methods, such as firstUpdated. Lit's documentation specifically mentions this as a method of adding listeners asynchronously, for example, when event listeners can only be added after the first render. If a component is removed from the DOM and destroyed, all event listeners on the component or its rendered template should be destroyed provided there are no further references to the instance of the element(s) on which they are attached. However, it's good practice to remove event listeners in the disconnectedCallback, and to avoid using the firstUpdated method if possible. What can be particularly dangerous is adding event listeners to the updated lifecycle method, as this can lead to multiple event listeners being added for the same event. This can lead to unexpected behaviour and memory leaks. If a use case arises for this, event listeners should be removed before being added again, or the state of any listeners checked before adding more.

Conclusion

When adding event listeners, the easiest and most consistent way is to utilise Lit's @ declarative syntax, which takes care of event deregistration automatically. If listeners need to be added outside of the component or its rendered template, the connectedCallback and disconnectedCallback lifecycle methods should be used. When adding event listeners imperatively, the callback function should be a named function, and the context of this must be considered carefully. Other lifecycle methods should be used only if necessary, with consideration of issues such as multiple registration and redundant listeners not being cleaned up.