Debounced

Debounced versions of native DOM events

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

Table of Contents

• Why?
• Install
• Quick Start
• Usage
  • Leading / Trailing Debounce
  • Custom Events
  • Unregistering Events
  • Debounced Event Prefix
• API
• FAQ
• Releasing

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 |

The source is small and well documented. Learn more about the API here.

FAQ

Q: What are the default native events that bubble?

A: View the list here and learn more about these events at MDN.

Q: Can I register an event more than once?

A: Yes, event re-registration overwrites any existing registrations.

Q: Do I have to specify all options when registering an event?

A: No, any omitted options will apply the defaults.

Q: Are importmaps supported?

A: Yes, this library is compatible with importmaps.

Testing

Clone the repo and run the following.

npm install
npm run test

Releasing

1. Run npm update to pick up the latest dependencies
2. Update the version at package.json and src/version.js - pre-release versions use -preN
3. Run npm run build
4. Commit and push any changes to GitHub
5. Run npm publish --access public
6. Create a new release on GitHub (here)