useEventListener

Purpose

Add an event listener to a Window|Document|Element that will be automatically cleaned up on controller disconnect. Automatically sets the correct Javascript binding so that this inside the event listener corresponds to the controller instance.

Side Effects

The controller will add an event listener on the given element, for the given event name.

Usage

There are two functions provided as part of this Mixin. useEventListener for events on a single element, or useCollectionEventListener for events bound to multiple elements.

useEventListener

Parameters		Type	Purpose	Default
controller		Controller	The instance of the controller to install the behaviour on. This allows the mixin to automatically register cleanup on the controller's disconnect.	this
element		Window or Document or HTMLElement	The element to add the event listener on
eventNameOrNames		String or Array<string>	The fully qualified name(s) of the event(s) you wish to listen for i.e. 'change or ['change', 'input', 'click']
handlerFunction		Function(event)	The function that will handle the event, receives a single parameter, which is the event that triggered the handler
options (Optional)		Object	Options to modify how the event listener is initialized	-
	debounce (Optional)	Number	The number of milliseconds to debounce the given handler by	-
	capture (Optional)	Boolean	A boolean value indicating that events of this type will be dispatched to the registered listener before being dispatched to any EventTarget beneath it in the DOM tree.	-
	once (Optional)	Boolean	A boolean value indicating that the listener should be invoked at most once after being added. If true, the listener would be automatically removed when invoked.	-
	passive (Optional)	Boolean	A boolean value that, if true, indicates that the function specified by listener will never call preventDefault(). If a passive listener does call preventDefault(), the user agent will do nothing other than generate a console warning. See Improving scrolling performance with passive listeners to learn more.	-
	signal (Optional)	AbortSignal	An AbortSignal. The listener will be removed when the given AbortSignal object's abort() method is called.	-

useCollectionEventListener

Parameters		Type	Purpose	Default
controller		Controller	The instance of the controller to install the behaviour on. This allows the mixin to automatically register cleanup on the controller's disconnect.	this
elements		An array of Window or Document or HTMLElement	The elements to add the event listener on
eventNameOrNames		String or Array<string>	The fully qualified name(s) of the event(s) you wish to listen for i.e. 'change or ['change', 'input', 'click']
handlerFunction		Function(event)	The function that will handle the event, receives a single parameter, which is the event that triggered the handler
options (Optional)		Object	Options to modify how the event listener is initialized	-
	debounce (Optional)	Number	The number of milliseconds to debounce the given handler by	-
	capture (Optional)	Boolean	A boolean value indicating that events of this type will be dispatched to the registered listener before being dispatched to any EventTarget beneath it in the DOM tree.	-
	once (Optional)	Boolean	A boolean value indicating that the listener should be invoked at most once after being added. If true, the listener would be automatically removed when invoked.	-
	passive (Optional)	Boolean	A boolean value that, if true, indicates that the function specified by listener will never call preventDefault(). If a passive listener does call preventDefault(), the user agent will do nothing other than generate a console warning. See Improving scrolling performance with passive listeners to learn more.	-
	signal (Optional)	AbortSignal	An AbortSignal. The listener will be removed when the given AbortSignal object's abort() method is called.	-

How to Use

import {Controller} from '@hotwired/stimulus';
import {useEventListener, useCollectionEventListener} from 'stimulus-library';

export default class extends Controller {

  connect() {
    // Add an event listener to the Window
    useEventListener(this, window, 'hashchange', this.handler)

    // Add an event listener to the controller root element
    useEventListener(this, this.element, "change", this.handler)

    // Add an event listener to the controller root element that only fires once
    useEventListener(this, this.element, "change", this.handler, {once: true})

    // Add a [debounced](https://css-tricks.com/debouncing-throttling-explained-examples/)
    // event listener to the controller root element
    useEventListener(this, this.element, "input", this.handler, {debounce: 1500})

    // Add multiple event listeners to the same handler
    useEventListener(this, this.element, ['change', "input"], this.handler)

    // Add multiple event listeners to the same handler
    useEventListener(this, this.element, ['change', "input"], this.handler)

    // Add multiple [debounced](https://css-tricks.com/debouncing-throttling-explained-examples/)
    // event listeners to the same handler
    useEventListener(this, this.element, "change", this.handler, {debounce: 1500})

    // Add event listeners to an entire collection of elements
    useCollectionEventListener(this, this.fooTargets, "change", this.handler)

    // Add multiple event listeners to an entire collection of elements
    useCollectionEventListener(this, this.fooTargets, ["change", "input"], this.handler)
  }

  handler() {
    console.log('Look at me run!')
  }

}