Debounced NPM | npm.io

Debounced

Debounced versions of native DOM events

This library uses event delegation to add debounced versions of native (and custom) bubbling DOM events.

Why?

Have you ever wired up event listeners for keyup, input, or mousemove? If so, you know that these events are dispatched frequently and often necessitate adding custom debounce functionality to your application.

What if you could simply listen for a debounced event instead? Now you can.

This technique pairs extremely well with libraries like Stimulus, TurboBoost Commands, and StimulusReflex. Here are some examples.

<input type="text" data-controller="example" data-action="debounced:input->example#work">
<input type="text" data-reflex="debounced:input->Example#work">

Install

npm install debounced

Quick Start

!TIP Add the following code to your JavaScript app's entry point. Somwhere like: app/javascript/application.js

Invoking initialize without arguments will register debounced events for all native DOM events that bubble.

import debounced from 'debounced'

// initialize without args to register all native DOM events that bubble
debounced.initialize()

You can also initialize with a custom list of events.

// initialize with a custom list of events
debounced.initialize(['click', 'input', 'keydown'])

// listen for debounced events
document.addEventListener('debounced:input', event => { ... })
document.getElementById('example').addEventListener('debounced:keydown', event => { ... })
document.querySelectorAll('a').forEach(a => {
  a.addEventListener('debounced:click', event => { ... })
})

Usage

Initialize with custom options.

debounced.initialize(debounced.defaultEventNames, { wait: 500, leading: true, trailing: false })

You can register additional events at any time.

// register more events after initialization
debounced.register(['change', 'mousedown'])

You can customize options for registered events by re-registering with different options.

// re-register events and to change options
debounced.register(debounced.registeredEventNames, { wait: 100 })

Leading / Trailing Debounce

You can specify when debounced events fire via the leading and trailing options.

leading - fires after the source event but before waiting
trailing - fires after the source event and after waiting

Leading and trailing events will only fire once per source event.

!NOTE If both leading and trailing are true, a debounced event will trigger before and after the timeout.

Custom Events

You can add debounced versions of custom events.

// register an individual custom event
debounced.registerEvent('custom-event', { ... })

// register a list of custom events
debounced.register(['custom-event-one', 'custom-event-two'], { wait: 150 })

Unregistering Events

You can unregiser events at any time.

// unregister a single event
debounced.unregisterEvent('keyup')

// unregister a list of events
debounced.unregister(['click', 'input', 'keydown'])

// unregister all events
debounced.unregister(debounced.registeredEventNames)

Debounced Event Prefix

!IMPORTANT Setting the prefix needs to be done before invoking initialize or register[Event].

You can change the prefix of the debounced event names.

debounced.prefix = 'custom-prefix' // must be set before invoking initialize
debounced.initialize()
document.addEventListener('custom-prefix:click', event => { ... })

API

Name	Description
`defaultEventNames`	List of native DOM events that bubble
`defaultOptions`	Default options applied when registering events
`initialize`	Initializes and registers debounced events
`prefix`	Prefix used for debounced event names (get/set)
`registerEvent`	Registers a single event for debouncing
`register`	Registers a list of events for debouncing
`registeredEventNames`	List of all registered event names
`registeredEvents`	All registered events with their options
`unregisterEvent`	Unregisters a single event
`unregister`	Unregisters a list of events