Listener Utilities

A tiny utility library for working with event listeners in 678 bytes.

Exposes addListener, removeListener functions.

This library will work with analytics or as a standalone package.

See live demo.

Why this package?

This package makes it a little easy to work with addEventListener & removeEventListener by returning a clean up function for both. This makes it easy to re-attach a listener or disable a listener with it's return function.

Additionally this package is backwards compatible with older browsers. This library is backwards compatible back to IE 8.

How to install

Install @analytics/listener-utils from npm.

npm install @analytics/listener-utils

API

Below is the api for @analytics/listener-utils.

addListener

Add an event listener to an element.

import { addListener } from '@analytics/listener-utils'

addListener('#button', 'click', () => {
  console.log('do stuff')
})

This method returns a cleanup function. When the cleanup function is called the event listener is removed.

import { addListener } from '@analytics/listener-utils'

const selectorOrNode = '#my-button'
const event = 'click'
const opts = {} // (optional) See opts at https://mzl.la/2QtNRHR
const handler = () => {
  console.log('wow you clicked it!')
}
// addListener returns a disable listener function
const disableListener = addListener(selectorOrNode, event, handler, opts)

// Detach the listener
const reAttachListner = disableListener()

// reAttach the listener
const disableAgain = reAttachListner()
// ...and so on

Below is an example of automatically disabling a click handler while an api request is in flight

import { addListener } from '@analytics/listener-utils'

const disableListener = addListener('#button-selector', 'click', (event) => {
  /* Fetch in progress.. Call disableListener to avoid duplicate calls */
  const renable = disableListener()

  fetch(`https://swapi.dev/api/people/?search=l`)
    .then((response) => {
      return response.json()
    })
    .then((json) => {
      console.log('data', json.results)
      // Success! Reattach event handler
      renable()
    })
    .catch((err) => {
      console.log('API error', err)
      // Error! Reattach event handler
      renable()
    })
})
// call disableFetchListener wherever you wish to disable this click handler

/*
HTML:

<button id="button-selector">
  Click Me
</button>
*/

See addEventListener docs for options

Fire an event once

import { addListener } from '@analytics/listener-utils'

addListener('#my-button', 'click', () => {
  console.log('will fire only once')
}, { once: true })

Fire an event on multiple event types

import { addListener } from '@analytics/listener-utils'

addListener('#my-button', 'click mouseover', () => {
  console.log('will fire on click & mouseover events')
})

removeListener

Removes an event listener from an element.

import { addListener, removeListener } from '@analytics/listener-utils'

const buttonSelector = '#my-button'
const simpleFunction = () => console.log('wow you clicked it!')
addListener(buttonSelector, 'click', simpleFunction)

const options = {} 
// (optional) See opts at https://mzl.la/2QtNRHR

// removeListener returns an enable listener function
const altSeletor = document.querySelector('#my-button')
const reAttachListener = removeListener(altSeletor, 'click', simpleFunction, options)

// Reattach the listener
reAttachListener()

See removeEventListener docs for options

once

Utility function to fire function exactly once.

import { once } from '@analytics/listener-utils'

function simpleFunction() {
  console.log('Fired')
}

const onceOnlyFunc = once(simpleFunction)

onceOnlyFunc()
// Fired
onceOnlyFunc()
// nothing fired

Alternative libs

• https://github.com/azu/ui-event-observer