# @analytics/listener-utils

> Backward compatible event listener library for attaching & detaching event handlers

Latest version **0.4.2** (published 2025-08-07) · MIT license · 0 weekly downloads

## Install

```sh
npm install @analytics/listener-utils
pnpm add @analytics/listener-utils
yarn add @analytics/listener-utils
bun add @analytics/listener-utils
```

## Health

**Score 50/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 0.4.2 |
| Published | 2025-08-07 |
| First published | 2021-04-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 98.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2669 |
| Author | David Wells |
| Maintainers | davidwells |
| Keywords | analytics, analytics-project, analytics-util, events, listeners |

## Links

- npm: https://www.npmjs.com/package/@analytics/listener-utils
- Repository: https://github.com/DavidWells/analytics/tree/master/packages/analytics-util-listener
- Homepage: https://github.com/DavidWells/analytics/tree/master/packages/analytics-util-listener#readme
- npm.io page: https://npm.io/package/@analytics/listener-utils

## Dependencies (1)

- [@analytics/type-utils](https://npm.io/package/@analytics/type-utils.md) ^0.6.4

## Alternatives

- [async-exit-hook](https://npm.io/package/async-exit-hook.md) — 3.7M weekly downloads
- [evnty](https://npm.io/package/evnty.md) — 7.2K weekly downloads
- [eleventy-plugin-asciidoc](https://npm.io/package/eleventy-plugin-asciidoc.md) — 3.5K weekly downloads
- [@jswork/next-get2get](https://npm.io/package/@jswork/next-get2get.md) — 945 weekly downloads
- [@dashersw/axon](https://npm.io/package/@dashersw/axon.md) — 934 weekly downloads

## Recent versions

- 0.4.2 (latest) — 2025-08-07
- 0.4.1 — 2025-08-06
- 0.4.0 — 2023-12-31
- 0.3.2 — 2023-05-27
- 0.3.1 — 2023-05-27
- 0.3.0 — 2022-03-18
- 0.2.10 — 2022-02-05
- 0.2.9 — 2022-01-03
- 0.2.8 — 2022-01-02
- 0.2.7 — 2021-12-12
- 0.2.6 — 2021-10-24
- 0.2.5 — 2021-10-17
- 0.2.4 — 2021-08-06
- 0.2.3 — 2021-08-05
- 0.2.1 — 2021-07-31
- … 6 more at https://npm.io/package/@analytics/listener-utils/versions

## README

<!--
title: Javascript event listener util
pageTitle: Event Listener Utils
description: Utility library for adding backwards compatible event listeners
-->

# Listener Utilities

A tiny utility library for working with event listeners in <!-- AUTO-GENERATED-CONTENT:START (pkgSize) -->`726 bytes`<!-- AUTO-GENERATED-CONTENT:END -->.

Exposes `addListener`, `removeListener` functions.

This library will work with [analytics](https://getanalytics.io) or as a standalone package.

[See live demo](https://utils-event-listener.netlify.app/).

### 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](https://www.npmjs.com/package/@analytics/listener-utils).

```bash
npm install @analytics/listener-utils
```

## API

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

## `addListener`

Add an event listener to an element. 

```js
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.

```js
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

```js
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](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener) for options 


Fire an event once

```js
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

```js
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.

```js
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](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/removeEventListener) for options 


## `once`

Utility function to fire function exactly once.

```js
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

---
_Source: https://npm.io/package/@analytics/listener-utils · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._